Async API

A local broker started with Docker Compose or Testcontainers, or a local emulator such as LocalStack, is the recommended setup.

Point Drift at your AsyncAPI document with a sources entry, then declare the plugins for your specification, transport, and payload format.

# yaml-language-server: $schema=https://download.pactflow.io/drift/schemas/drift.testcases.v1.schema.json
drift-testcase-file: v1
title: "Order service AsyncAPI verification"

sources:
  - name: order-async
    path: ./asyncapi/order.asyncapi.yaml

plugins:
  - name: asyncapi     # loads the AsyncAPI document and plans the interaction
  - name: kafka        # the transport
  - name: json         # payload validation

Every AsyncAPI test file needs three plugins:

Use aws-messaging in place of kafka for Amazon SNS and SQS. See AWS Messaging Plugin.

An AsyncAPI target has up to three segments:

target: <source-name>:<operation-id>:<message-id>

# Full form, naming the message explicitly
target: order-async:sendOrderCreated:orderCreated

The message segment selects which message to use when an operation defines more than one. You can omit it when the operation defines exactly one message:

target: order-async:sendOrderCreated

If an operation defines several messages and you omit the segment, Drift fails during planning and tells you which messages are available.

operations:
  SendOrderCreated_Observe:
    target: order-async:sendOrderCreated:orderCreated
    description: "Observe the order.created event emitted after the trigger runs"
    parameters:
      correlation-id: send-order-created-001
      timeout-ms: 5000
      orderId: ORD-100
      customerId: CUST-9
    trigger:
      executable-type: command
      value: python3
      parameters:
        args:
          - ./hooks/trigger-send.py
          - --correlation-id
          - ${parameters.correlation-id}
          - --order-id
          - ${parameters.orderId}
      timeout-ms: 2000
    expected:
      headers:
        correlation-id: ${parameters.correlation-id}
      payload:
        eventType: order.created
        orderId: ${parameters.orderId}
        customerId: ${parameters.customerId}
        status: created

Drift chooses how to run the operation based on the AsyncAPI action and your inputs. You do not normally set this yourself.

AsyncAPI 3 actions are written from your application's perspective. An operation with action: send means your service publishes, so Drift captures. An operation with action: receive means your service consumes, so Drift publishes. Drift's role is always the opposite of your service's.

For the full definition of each mode, see AsyncAPI Execution Modes.

These parameters apply to AsyncAPI operations. Set them under parameters.

Transport plugins accept their own parameters as well. See the Kafka Plugin and AWS Messaging Plugin plugin pages.

When Drift subscribes to a channel, other traffic may be present. Correlation tells Drift which message is the one it is waiting for.

Declare the location in your AsyncAPI message. This is the part you must supply - it tells Drift where to read and write the identifier, and correlation is inactive without it.

components:
  messages:
    orderCreated:
      correlationId:
        location: "$message.header#/correlation-id"

The value is optional. Drift resolves it in this order:

Set the value yourself when something outside the operation needs the same identifier - a trigger hook, a probe command, or an expectation. Omit it and let Drift generate one when nothing else needs to know it:

parameters:
  correlation-id: send-order-created-001
expected:
  headers:
    correlation-id: ${parameters.correlation-id}

Using ${parameters.correlation-id} rather than repeating the literal keeps the trigger hook, the published message, and the expectation in step.

Where you do set a value, give each operation a distinct one. Reusing a value across operations lets a message from an earlier test satisfy a later one.

timeout-ms bounds how long Drift waits for a message before failing.

parameters:
  timeout-ms: 5000

Too short produces flaky failures against a slow service. Too long makes a genuinely broken service slow to report. A few seconds is a reasonable starting point for a local broker.

Hooks have their own timeout-ms, which bounds the hook process rather than the capture. When a hook omits it, the operation-level timeout-ms applies.

Drift resolves connection details from three places. Higher priority wins.

Committing a local server to your AsyncAPI document gives every developer a working default:

servers:
  local:
    host: localhost:9092
    protocol: kafka
    description: Local Kafka broker

Override it per environment through plugin configuration, and per test through the test case when you need to.

The expected block states what a pass looks like. Its shape depends on whether Drift captures a message or reads probe output.

When Drift captures a message - async-observe, async-inject-capture, and async-request-reply - use payload and headers:

expected:
  headers:
    correlation-id: ${parameters.correlation-id}
  payload:
    eventType: order.created
    status: created

When Drift reads probe output - async-inject - the expected block matches the JSON your probe returns:

expected:
  status: processed
  correlationId: ${parameters.correlation-id}

Drift also validates captured messages against the schemas in your AsyncAPI document. The expected block adds value assertions on top of schema conformance, so you do not need to restate every field the schema already covers.