Add reboot.bdd: write Reboot tests in Gherkin with pytest-bdd

[benh]

Adds reboot.bdd, a pytest-bdd layer for testing Reboot applications with Gherkin, plus its test suites.

What a test looks like

Feature: Accounts

  Background:
    Given the application is up
    And the user is unauthenticated

  Scenario: Depositing adds to the balance
    Given an `Account` for "alice" gets created via `open` with `initial_balance=100`
    When the `Account` for "alice" gets a `deposit` with `amount=50`
    Then the result has `updated_balance=150`
    And `balance` on the `Account` for "alice" has `balance=150`

The test module does from reboot.bdd.steps import * and defines an application fixture returning the Application under test. Each scenario runs against a fresh started Reboot harness, and each step's call runs on a fresh ExternalContext (the way each external call in production arrives with its own) unless the scenario creates one to share via Given a shared context.

Built-in steps

• Given the application is up
• Given a shared context
• Given the authenticated user is "alice" — mints a valid test token for that user ID through the application's own OAuth server and puts it on every context created from then on, so servicers see context.auth.user_id; Given the user is unauthenticated calls with no token; Given the bearer token is "..." sets a raw token instead (e.g. an admin key). All work as When too, so scenarios switch users mid-flight; say who calls before Given a shared context. Every scenario must say who calls before its first call — a call before any of these raises naming the spellings, so a reader always sees whether authentication is in play.
• Given an `Account` for "alice" gets created via `open` with `initial_balance=100` (usable as When too)
• When the `Account` for "alice" gets a `deposit` with `amount=50` (usable as Given too)
• When the `Account` for "spawned" gets a `deposit` with `amount=15` spawned with its task id saved as `first` — the call runs as a task; then Then the `deposit` task with id "${first}" of the `Account` completes within 30 seconds awaits it (bound required) and records its response as the result. A task_id a response carries saves and awaits identically.
• When the `Account` for "bob" attempts a `withdraw` with `amount=50`
• Then the attempt aborts with `OverdraftError` with `amount=20`
• Then `balance` on the `Account` for "alice" has `balance=150`
• Then `balance` on the `Account` for "alice" eventually has `balance=150` within 30 seconds — holds a reactive read open, asserting against each response, until the assertions hold or the bound expires; the bound is required because plain pytest has no timeout backstop, and expiry reports the last response's mismatch like a failed assert.
• Then `balance` on the `Account` for "ghost" aborts with `StateNotConstructed`
• When `get_owner` on the `Account` for "frank" has `owner.name` saved as `owner_name` (later steps recall it as ${owner_name} in a state's ID, a user's ID, a bearer token, a property value, or a predicate argument; a quoted "${owner_name}" stays the literal string)
• Then the result has `updated_balance=150` (as Given/When, saves instead)

The property grammar

A has/with list holds `path=value` assignments, each in backticks, separated by commas or and. The left side is a property path: dots nest, [0] indexes a list, ["key"] reaches into a map. The right side is JSON, with JSON5's leniencies (object keys need no quotes), and an object or array value calls through the method's request type; on assertions it compares as the complete message.

An asserting list (a Then has, or the clause list after an abort's error type) can also say two predicates: `path` containing `value` asserts a substring of a string, an element of a list (compared under the response type's semantics, the way = compares), or a key of a map; `path` of length `n` asserts the length of a string, list, or map. A predicate's backticked argument is a JSON value the way a property's value is — one grammar, one parser — so it can recall ${name} (a length may come from a save too), while the counts in a sentence itself, like within 30 seconds, stay bare words. A Given/When has instead saves: `path` saved as `name` — backticks are where the grammar binds names and holds JSON values, ${name} is where it uses them.

A malformed or unknown property raises instead of being skipped, and a lexical near-miss of the grammar (: for =, contains for containing, a missing backtick, an assert-shaped clause under the saving keyword, a predicate in a call's with, ...) raises an Almost: ... error naming the fix rather than pytest-bdd's "step definition is not found".

Readers are only read via `reader` on ...; gets a/attempts a refuse them with a pointing error, and the reader steps refuse writers likewise (whether a method is a reader comes from the generated reactively() surface, which serves exactly the unary readers). Reading records the result, so "the result" always means the most recent call any step made.

State types are resolved from the Application's servicers by class name, or by full state type name (e.g. bank.v1.Account) when more than one state type goes by the class name; both proto and pydantic codegen are supported.

The examples' tests are the proof

Six example applications' test suites are converted to Gherkin on this branch — chat-room, monorepo/hello-constructors, monorepo/bank (both suites), bank-pydantic, chick-potle, and agent-wiki — each with assert-for-assert parity audited against its old unittests, and each run end-to-end through its own test.sh: fresh venv, the built wheel with the pytest-bdd extra, rbt generate, mypy, pytest. Conventions that emerged: a custom step is plain Reboot code (a context from world.context(), which carries the scenario's authenticated user, then calls on the generated clients); test-only stand-ins (mocked email senders, scripted LLM models, authorizer-wiring servicer subclasses) live as fixtures beside the application fixture; and a fixture may save values (world.saved['name'] = ...) for scenarios to recall as ${name}.

How it works

pytest and pytest-bdd are synchronous while everything Reboot is async, and we deliberately don't use pytest-asyncio (pytest-bdd never awaits step functions, so it wouldn't help anyway). Instead, each scenario runs one event loop on a background thread, created before its first step and closed after its last: one loop per scenario, matching both unittest.IsolatedAsyncioTestCase (one loop per test) and production (one application runs on one event loop under rbt dev run and rbt serve), so nothing a scenario leaks can run on into later scenarios. The loop's teardown mirrors IsolatedAsyncioTestCase: cancel pending tasks, shut down async generators, close.

The reboot.bdd given/when/then/step decorators work like pytest-bdd's except that the decorated step function may be async def, so custom developer steps get the same treatment as the built-ins (exercised by the custom steps in tests/reboot/bdd/bdd_tests.py and tests/reboot/bdd/pydantic/bdd_tests.py).

Also in this PR

• Reboot.stop() now cancels (via wait_for_tasks) the monitor_event_loop() task that start() creates. IsolatedAsyncioTestCase hid this leak by closing its per-test loop; on a longer-lived loop every harness left a pending task behind. Ran //tests/reboot:external_context_tests_py to check for regressions, but this touches every harness user, so please look closely.
• pytest==8.4.2, pytest-bdd==8.1.0, jsonpath-ng==1.8.0 (property paths), and json5==0.15.0 (property values) added to reboot/requirements.in (and mypy.ini ignore sections for each).

Testing

bazel test //tests/reboot/bdd:bdd_tests_py //tests/reboot/bdd/pydantic:bdd_tests_py (proto and pydantic suites, plus unit tests for name collisions, unknown properties, and reader detection).

Not yet done (follow-ups)

• The published wheel should probably get pytest-bdd as a reboot[bdd] extra rather than a hard dependency; only the Bazel side is wired here.
• Docs (a testing-bdd.md skill reference), state assertions via a test-only raw-state read (e.g. Then the state of the `Account` for "alice" has `balance=70` ), and failure/recovery steps.

🤖 Generated with Claude Code

https://claude.ai/code/session_015whh5EmdU8PAoxSevMRn5m

[aviator-app]

Current Aviator status

Aviator will automatically update this comment as the status of the PR changes.
Comment /aviator refresh to force Aviator to re-examine your PR (or learn about other /aviator commands).

This pull request is currently open (not queued).

How to merge

To merge this PR, comment /aviator merge or add the mergequeue-ready label.

---

See the real-time status of this PR on the Aviator webapp.

Use the Aviator Chrome Extension to see the status of your PR within GitHub.