Copy the block below into a .feature file and replace the <placeholders>.
@events @orders
Feature: Order events are published and consumed
Background:
Given the event broker is healthy
And the consumer "fulfilment" is subscribed to topic "orders.v1"
@publishing
Scenario: Creating an order publishes an order-created event
Given order "A-1042" does not exist
When order "A-1042" is created with 2 items
Then an event "orders.v1.order-created" is published within 5 seconds
And the event payload contains order id "A-1042"
And the event payload contains 2 items
And the event carries an event id
And the event carries the schema version "1"
@idempotency
Scenario: The same event delivered twice is processed once
Given an event "evt-77a1" with payload for order "A-1042" has been delivered
When event "evt-77a1" is delivered again
Then the consumer processes order "A-1042" exactly once
And the consumer acknowledges event "evt-77a1"
@idempotency
Scenario: A different event with the same payload is processed
Given an event "evt-77a1" with payload for order "A-1042" has been delivered
When event "evt-91c4" with the same payload is delivered
Then the consumer processes order "A-1042" a second time
@ordering
Scenario: Events for the same order are delivered in order
Given order "A-1042" exists
When order "A-1042" is paid and then shipped
Then the consumer receives "order-paid" before "order-shipped"
And the consumer's state for order "A-1042" is "shipped"
@ordering
Scenario: Events for different orders are not ordered against each other
Given order "A-1042" and order "A-1043" both exist
When order "A-1043" is shipped
And order "A-1042" is paid
Then the consumer may receive either order first
And both orders reach a consistent state
@failure
Scenario: A message that repeatedly fails is moved to the dead-letter queue
Given the consumer "fulfilment" always fails to process order events
When order "A-1042" is created
And 3 delivery attempts are exhausted
Then the event is moved to the dead-letter queue
And the event is not redelivered
And an alert is raised for the dead-lettered event
@failure
Scenario: A message that fails once is redelivered
Given the consumer "fulfilment" fails to process the next order event once
When order "A-1042" is created
Then the event is redelivered
And the consumer processes order "A-1042" exactly once
And the event is acknowledged
Notes on each part
The event id is the idempotency key. Every event carries a stable identifier, and the consumer deduplicates on it. The template states both halves of that: the producer emits an id, and the consumer processes an event id once.
"A different event with the same payload is processed" is the scenario people forget. Deduplication on payload content is a common and wrong implementation: two genuinely distinct orders with identical contents get collapsed into one. If your consumer deduplicates on the event id, say so explicitly, because the alternative is a real bug.
Ordering is specified per key, not globally. The template states that events for the same order are ordered, and that events for different orders are not. Global ordering is expensive and almost never required, and the specification is where you decide which one you actually need.
The "may receive either order first" clause looks odd but is not. It says the outcome is unconstrained, which is exactly what lets an implementation be parallel. Without it, a reviewer will assume ordering is required and will ask for a guarantee you do not want to make.
Redelivery and dead-lettering are separate scenarios. The distinction is between "failed and will be tried again" and "failed and will not", and the two have completely different operational consequences. A consumer that dead-letters on the first failure loses data; one that retries forever stalls the queue.
The dead-letter scenario asserts three things: the event moved, redelivery stopped, and an alert was raised. The third is the one that gets skipped, and it is the one that turns a silent data loss into an incident somebody looks at.
Pair it with an event schema
The template specifies behaviour. The event’s own shape — field names, types, optionality — belongs in a schema, in your repository, versioned alongside the topic name.
Two things to get right:
The schema version travels with the event. The template asserts the event carries the schema version "1". A consumer that cannot tell which schema it received cannot reject a payload it does not understand, and will instead process it wrongly.
The topic name includes the major version. orders.v1 rather than orders. That is what lets a breaking change ship without coordinating every consumer at once.
Related
- Gherkin feature files — the conventions behind this template
- Gherkin for IoT device fleets — the same retry and idempotency problems, in a different domain
- Assertion strength — why "the event was published" needs an assertion