AsyncAPI Execution Modes

    A["AsyncAPI operation<br/>in your document"] --> B{"Does the operation<br/>define a reply?"}
    B -->|Yes| RR["<b>async-request-reply</b><br/>Publish a request,<br/>capture the correlated reply"]
    B -->|No| C{"What is the<br/>operation action?"}

    C -->|"<b>send</b><br/>your app publishes"| OBS["<b>async-observe</b><br/>Subscribe, fire trigger,<br/>capture and validate"]

    C -->|"<b>receive</b><br/>your app consumes"| D{"Did you set<br/>probe-topic?"}
    D -->|No| INJ["<b>async-inject</b><br/>Publish, run probe command,<br/>validate probe output"]
    D -->|Yes| IC["<b>async-inject-capture</b><br/>Subscribe to probe topic,<br/>publish, capture result"]

    style RR fill:#e8f4f8,stroke:#2b7a9b,color:#0b2b36
    style OBS fill:#e8f4f8,stroke:#2b7a9b,color:#0b2b36
    style INJ fill:#e8f4f8,stroke:#2b7a9b,color:#0b2b36
    style IC fill:#e8f4f8,stroke:#2b7a9b,color:#0b2b36

AsyncAPI 3 actions describe what your application does. An operation with action: send means your application publishes, so Drift captures. An operation with action: receive means your application consumes, so Drift publishes.

An explicit execution-mode parameter always takes precedence over the automatic selection. Drift validates mode preconditions before it contacts the broker, so an unsatisfiable combination fails immediately.

Drift subscribes to the channel, runs your trigger hook to make your service publish, then captures and validates the message.

Use this mode to verify events your service emits.

sequenceDiagram
    autonumber
    participant D as Drift
    participant B as Broker
    participant S as Your service

    D->>B: Subscribe to the channel
    D->>S: Run the trigger hook
    S->>B: Publish message
    B-->>D: Deliver matching message
    D->>D: Validate against the AsyncAPI schema

Required test case fields

Validation. Drift validates the captured payload against the message payload schema in your AsyncAPI document, and the captured headers against the headers schema when one is defined. Values you state under expected are compared in addition to schema validation.

Common failures. A capture timeout means no message matching your correlation ID arrived in time. Check that the trigger hook actually ran, that it used the same correlation ID, and that your service published to the channel address in the document.

Drift publishes the message, then runs your probe hook and compares what it returns against your expectations. Drift does not capture anything from the broker in this mode.

Use this mode when your service consumes a message and the evidence it worked is somewhere other than the broker — a database row, a REST endpoint, or a file.

sequenceDiagram
    autonumber
    participant D as Drift
    participant B as Broker
    participant S as Your service
    participant E as Side effect

    D->>B: Publish the message
    B-->>S: Deliver the message
    S->>E: Process and record the result
    D->>D: Run the probe hook
    D->>E: Probe queries the side effect
    E-->>D: Probe returns JSON evidence
    D->>D: Compare against expectations

Required test case fields

Validation. Drift compares the probe output against the expected block. It does not schema-validate the probe output, because the probe result is not described in your AsyncAPI document. The payload Drift publishes is validated against the message schema before it is sent.

Probe output must be JSON written to standard output.

Timing. Drift runs the probe as soon as the publish completes. If your service takes time to process, the probe must handle that itself by polling or retrying.

Drift subscribes to a probe topic, publishes the message to the input channel, optionally runs a trigger hook, then captures the result your test harness writes to the probe topic.

Use this mode when your test harness can publish its result back to a topic. It removes the race condition inherent in polling for a side effect.

sequenceDiagram
    autonumber
    participant D as Drift
    participant B as Broker
    participant S as Your service
    participant E as Side effect

    D->>B: Publish the message
    B-->>S: Deliver the message
    S->>E: Process and record the result
    D->>D: Run the probe hook
    D->>E: Probe queries the side effect
    E-->>D: Probe returns JSON evidence
    D->>D: Compare against expectations

Required test case fields

The probe topic must be on the same broker as the injection target. The same transport plugin handles both the subscription and the publish.

Probe output must be JSON written to standard output.

Probe topic messages must be JSON. The probe topic is test infrastructure and is not described in your AsyncAPI document, so Drift cannot derive a schema or content type for it. Drift parses probe topic messages as application/json and compares them against your expected block without schema validation. If you need a different wire format, use async-inject with a standard probe hook instead.

Drift subscribes to the reply channel, publishes the request, then captures and validates the correlated reply.

Use this mode when the AsyncAPI operation declares a reply and the reply arrives on the same transport.

sequenceDiagram
    autonumber
    participant D as Drift
    participant RQ as Request channel
    participant S as Your service
    participant RP as Reply channel

    D->>RP: Subscribe to the reply channel
    D->>RQ: Publish the request<br/>with correlation ID and reply-to
    RQ-->>S: Deliver the request
    S->>RP: Publish the correlated reply
    RP-->>D: Deliver the matching reply
    D->>D: Validate the reply against<br/>the AsyncAPI schema

Required test case fields

Validation. Drift validates the reply message against the reply message schema in your AsyncAPI document. The request is validated against the request message schema before it is published.

Reply address. When the AsyncAPI operation's reply declares an address.location, Drift sets that value from the reply channel address. In the common case where the location is $message.header#/reply-to, Drift sets a reply-to header on the request.

Cross-transport replies are not supported. The reply must arrive on the same transport as the request.

Set execution-mode in the operation parameters:

operations:
  SendOrderCreated_Observe:
    target: async-send:sendOrderCreated:orderCreated
    parameters:
      execution-mode: async-observe

Drift validates the preconditions for the mode you name. async-inject-capture requires a probe-topic parameter. async-request-replyrequires either a reply in the AsyncAPI operation or a reply-channel parameter. If a precondition is unmet, Drift fails before contacting the broker.