Guides

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.

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.

Next