Copy the block below into a .feature file and replace the <placeholders>.
@api @orders
Feature: Manage orders
Background:
Given an authenticated customer "C-88"
And order "A-1042" exists with status "new"
And order "A-1043" exists with status "new"
And order "A-1044" exists with status "shipped"
@happy-path
Scenario: Listing orders returns the customer's orders
When the customer requests their orders
Then the response status is 200
And the response contains orders "A-1042" and "A-1043"
And the response does not contain order "A-1044"
@pagination
Scenario: Listing orders paginates
Given the customer has 25 orders
When the customer requests their orders with a page size of 10
Then the response status is 200
And the response contains 10 orders
And the response reports 25 orders in total
And the response reports 3 pages in total
@pagination
Scenario: Requesting a page beyond the last page returns an empty list
Given the customer has 25 orders
When the customer requests their orders with a page size of 10 and page number 4
Then the response status is 200
And the response contains 0 orders
And the response reports 25 orders in total
@errors
Scenario: Requesting an unknown order returns not found
When the customer requests order "A-9999"
Then the response status is 404
And the response body contains error code "ORDER_NOT_FOUND"
@errors
Scenario: Requesting an order belonging to another customer is refused
When the customer requests order "A-7777"
Then the response status is 403
And the response body contains error code "ORDER_ACCESS_DENIED"
@errors
Scenario: Requesting an order without authentication is refused
Given an unauthenticated request
When the request is made for order "A-1042"
Then the response status is 401
And the response body contains error code "AUTHENTICATION_REQUIRED"
@validation
Scenario: A page size above the maximum is refused
When the customer requests their orders with a page size of 500
Then the response status is 422
And the response body contains error code "PAGE_SIZE_TOO_LARGE"
And the response body states the maximum page size is 100
Notes on each part
The @tags carry meaning. They drive targeting, traceability to requirements, and severity. A tag that references a requirement ID is what turns "we have nine scenarios" into "requirements R-1 through R-9 each have a scenario and R-10 does not".
Background holds state, not actions. Every Given there is true before each scenario. If you find yourself adding a When to a Background, the scenarios have hidden their actual sequence and you should split them.
The pagination scenarios are the ones worth keeping. Two details are usually missing from a team’s own feature file:
- The empty page beyond the last one. Almost every implementation gets this right by accident and a few get it wrong by returning a 404. Specify it.
- The maximum page size. A limit that is not specified is a limit that does not exist until someone adds one. And when they do, the refusal is a breaking change for every client that was relying on the larger value.
The 403 and the 404 are different scenarios. Not-found and access-denied are different answers with different information leakage implications. A service that returns 404 for both is a deliberate choice, and it should be written down as one rather than as an accident.
The error codes are literal. ORDER_NOT_FOUND is checkable. "an appropriate error" is not — and it is exactly the kind of phrase that turns into an assertion-free scenario.
Pair it with an OpenAPI document
This template covers behaviour. The interface — paths, parameters, response schemas — belongs in the OpenAPI document, and the platform checks the two against each other. The error codes above must appear as operationId-scoped error responses in the document, or the cross-format consistency check will fail the build.
See OpenAPI contract testing for the contract side.
Related
- Gherkin feature files — the conventions behind this template
- Cross-format consistency — why the two halves have to agree
- Assertion strength — check the assertions, not just the scenarios