Templates

Templates are starting points, not standards. Each one is a working shape for a common kind of specification, with the parts that are usually forgotten already filled in — the negative cases, the boundary rows, the failure paths.

How to use these

Copy, then delete. A template with everything in it teaches you the shape of a complete specification, and a specification with everything in it is too long to review. Take what applies, and delete the rest.

The placeholders are marked. Anything you need to decide is written as <like this>. If a placeholder is still there when you start reviewing, the specification is not ready.

Keep the negative cases. They are the part of every template that people delete first, and they are the part that catches defects. If you cut a scenario, cut the positive one, and keep the one that says what must not happen.

Adapt the conventions. The step phrasing and tag structure here are one reasonable house style. If your team already has a style, use yours — the platform follows the conventions already in your repository.

What every template gets right

These are the properties the templates share, and they are the properties that make a specification worth reviewing:

  • A Background with state, not actions. Everything in the Background is true before each scenario.
  • At least one negative case per feature. Not per scenario — per feature. A feature with no scenario describing what must not happen is not specified.
  • The boundary value present. Where a limit exists, the value exactly on the boundary is asserted, not just the values on either side.
  • Failure paths are specified. What happens when the dependency fails is a rule, and rules belong in clauses.
  • Explicit values. "The order status becomes refunded" rather than "the order status is updated".
  • Error codes are literal. REFUND_WINDOW_CLOSED, not "an appropriate error".

What these templates do not include

Authentication and authorisation setup. Usually noise in a feature file — it is the same in every scenario and rarely the interesting part. Where authorisation is the behaviour under test, it belongs in the scenario; otherwise it belongs in the Background.

Detailed validation rules. Field-level validation belongs in the OpenAPI document, where it is enforced structurally. A feature file that restates every schema constraint duplicates the contract and doubles the review.

Performance and load expectations. Those are SLOs, tested by performance tests, not acceptance criteria.

Contributing

If you have written a template that works well for a domain we have not covered, we would like to see it. Send it to contact us with a note about the domain it is for. We publish contributed templates under the same terms as the rest of the documentation.