Event-driven behaviour template

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.

Next