Generic tutorials on "how to write Gherkin" are everywhere, and most of them are not what you need. The hard part of specification is not the syntax — it is deciding what to state, what to leave implicit, and where the boundary between specification and implementation sits.
That boundary moves depending on the domain. A payment refund has invariants you must state; an IoT fleet has retry semantics you must state; a trading risk rule has thresholds you must state exactly. These guides are organised by domain, because the domain is what determines the shape of a good specification.
Gherkin for game backend APIsMatchmaking, inventories, and the state machines players actually hit
OpenAPI contract testing for REST servicesUsing the contract as the test, and catching breaks before deploy
Gherkin for trading and risk rulesThresholds, limits, and stating numeric rules precisely
Gherkin for IoT device fleetsOffline behaviour, retry semantics, and command acknowledgements
Spec-driven development versus BDDWhat actually changed, and whether it is worth the switch
What these guides are
Each guide follows the same shape:
- The domain’s failure modes — what actually goes wrong here, and which of them a specification can catch.
- What to state and what to leave implicit — because a specification that states everything is too long to review, and one that states nothing verifies nothing.
- A worked pattern — a real excerpt in Gherkin or OpenAPI, with the reasoning attached.
- The review question — the single question to ask about each clause, specific to this domain.
They are deliberately not complete references. They are the parts of the practice that are specific to the domain, because the generic parts are already well documented by the Gherkin and OpenAPI projects themselves.
A note on vertical focus
The platform is built for domains where behaviour can be stated precisely and checked mechanically. The guides here are the domains we have found that property holds in.
If your domain is not on this list, the techniques usually transfer — but start from your own failure modes, not from an example. A specification built from a domain’s real failure modes will be better than a specification copied from someone else’s example.
Gherkin for game backend APIsMatchmaking, inventory limits, reconnection and seasonal rules — where game backends actually break.
OpenAPI contract testing for REST servicesUsing the OpenAPI document as the test — and the four checks that make it worth writing.
Gherkin for trading and risk rulesThresholds, boundaries, aggregation windows and stale data — the four things a risk specification must pin down.
Gherkin for IoT device fleetsOffline behaviour, retry semantics, acknowledgements and staged rollout — where fleet specifications break.
Spec-driven development versus BDDAn honest comparison — what changed, what did not, and when it is not worth the switch.