executable specs via step definitions — run scenarios directly against the system

[clay-good]

Note

Moved from issue #987, originally opened by @jhonathas on 2026-04-18. Continuing the conversation here in Discussions — the original issue thread (including any comments) stays available at #987 for the record.

---

Problem

Currently, OpenSpec specs (WHEN/THEN/AND scenarios) are documentation —
they describe behavior but cannot be executed. The only way to verify them
is to write separate tests manually, which creates two artifacts to maintain
and risks specs drifting from the actual test suite over time.

Proposed Solution

Make specs executable via step definitions, similar to how Cucumber/Gherkin
works in Rails or White Bread does in Elixir.

The spec file remains the single source of truth. Developers write step
definitions that map WHEN/THEN clauses to real code. OpenSpec runs the
scenarios directly against the system.

Proposed command: openspec test --change <name> [--spec <capability>]

How it would work

1. OpenSpec parses each #### Scenario: block from the spec files
2. For each WHEN/THEN clause, it looks up a matching step definition
3. Step definitions are project-side code (e.g. test/steps/) that map
   natural language patterns to actual assertions
4. Unmatched steps are reported as "pending" — not failures

Example spec (unchanged):
#### Scenario: Login bem-sucedido
- WHEN usuário submete email e senha corretos
- THEN sistema cria registro em user_sessions
- AND redireciona para /

Example step definition (developer writes once, reuses across scenarios):
step ~r/usuário submete email e senha corretos/, fn ctx ->
end

step ~r/sistema cria registro em user_sessions/, fn ctx ->                                       
  assert Repo.get_by(UserSession, user_id: ctx.user.id)                                          
end                                                           

Why this matters

• Spec IS the test — no duplication, no drift
• Specs stay honest: if a scenario can't be stepped, it gets flagged
• Step definitions are reusable across capabilities and changes
• Completes the spec-driven loop: write spec → write steps → run → pass
• Familiar model for anyone coming from Cucumber, Gherkin, or White Bread (Elixir)

Prior art

• Cucumber + Capybara (Ruby/Rails)
• White Bread (Elixir) — https://github.com/meadsteve/white_bread
• Behave (Python)
• Godog (Go)