bdd-specs

Executable Gherkin specifications

features/ holds the product contract. Every use case is written here in Gherkin before the unit tests and before the implementation, and every scenario is executable: npm run bdd runs them all.

Layout

features/
├── <use-case>.feature        # Gherkin, business language
├── steps/<use-case>.steps.ts # thin translation layer, Given/When/Then
└── support/world.ts          # per-scenario state, hooks, fixture loading

One .feature per use case, named after the user-visible outcome (trip-from-topic.feature, stay-dates.feature, checkout-links.feature), not after a module. Step definitions may be shared across features; put reusable steps in the file whose feature owns them and import nothing between step files.

How a scenario is written

• Business language only. No HTTP verbs, no tool names, no function names, no CSS selectors inside a .feature. A step describes what a traveller or an agent observes. Bad: When I call search_multitransport with origin Москва. Good: When the trip is assembled from Москва.
• Given sets up recorded world state, When performs exactly one action, Then asserts one observable outcome. Chain with And rather than stuffing two actions into one When.
• Scenario Outline for rule tables. The date algorithm, the feasibility checks and the three package rules are naturally tabular and must be specified that way, so the spec itself becomes the readable statement of the algorithm.
• Honesty scenarios are first-class. Missing venue coordinates, a checkout link that is not a cart, an unparsed event price, a source that timed out: each is a specified behavior with its own scenario, not an edge case to be discovered later.
• Keep Gherkin keywords in English; the narrative inside a step may name Russian cities and events verbatim, because that is the real data.

Rules for step definitions

• Steps are thin: translate the sentence into a call into src/, then assert. No business logic, no date arithmetic, no price arithmetic inside a step.
• Scenario state lives on the World (features/support/world.ts), never in module-level variables. Cucumber builds one World per scenario, which is what keeps scenarios isolated.
• Assertions use node:assert/strict.
• Ambiguous or duplicate step definitions are a hard error (strict: true in cucumber.mjs). Reuse an existing step instead of writing a near-copy.
• Run npm run bdd after adding a step to a feature; Cucumber prints a ready snippet for every undefined step (snippetInterface: 'async-await').