Skip to main content
Swagger
All documentation pages

AsyncAPI Plugin

The AsyncAPI plugin loads AsyncAPI documents and exposes their operations as Drift targets. It is the foundational plugin for message-based testing, in the same way the OAS plugin is for HTTP.

The plugin plans each interaction: it resolves the operation and message, selects an execution mode, and works out the transport and payload details. It does not talk to a broker itself - that is the transport plugin’s job.

Property Value
Plugin name asyncapi
Purpose Loads AsyncAPI documents, exposes operations, validates messages
File types .yaml, .yml, .json
Requires A transport plugin and a data-format plugin

Enabling the Plugin

An AsyncAPI test file always needs three plugins.

plugins:
  - name: asyncapi        # this plugin
  - name: kafka           # or aws-messaging
  - name: json            # payload validation
Plugin Role
asyncapi Reads the document and plans the interaction
kafka or aws-messaging Connects to the broker and moves messages
json Builds and validates message payloads

Specification Support

Specification Support status
AsyncAPI 3.1 Supported
AsyncAPI 3.0 Supported
AsyncAPI 2.x Not supported

Transport Support

Protocol Plugin Asynchronous Request/reply
Kafka kafka Supported Supported
Amazon SNS aws-messaging Supported Not supported
Amazon SQS aws-messaging Supported Not supported

Payload Support

Content type Support status
application/json Supported through the json plugin
application/vnd.google.protobuf and other protobuf content types Supported through the protobuf plugin
application/vnd.apache.avro and other Avro content types Supported through the avro plugin

Probe topic messages are always parsed as application/json, regardless of the document’s defaultContentType. The probe topic is test infrastructure and is not described in the AsyncAPI document, so no schema can be derived for it.

Targeting Operations

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

The message segment is optional when the operation defines exactly one message:

target: order-async:sendOrderCreated
target: order-async:sendOrderCreated:orderCreated

If an operation defines several messages and no message segment is given, planning fails and Drift lists the available messages.

What the Plugin Reads from Your Document

Element Used for
operations.<id>.action Selecting the execution mode
operations.<id>.channel The channel address to publish to or subscribe to
operations.<id>.messages The message to send or validate
operations.<id>.reply Selecting async-request-reply, and locating the reply address
servers Default connection details
components.messages.<id>.payload Payload schema validation
components.messages.<id>.headers Header schema validation
components.messages.<id>.correlationId Where the correlation identifier lives
defaultContentType Selecting the data-format plugin
Protocol bindings Passed to the transport plugin for interpretation

Protocol bindings at the operation, channel, and message levels are filtered to the active protocol and handed to the transport plugin. See the plugin page for that transport for what it supports.

Execution Modes

The plugin selects a mode from the operation and your test case inputs. An explicit execution-mode parameter always wins.

AsyncAPI Inputs Mode
send N/A async-observe
receive N/A async-inject
receive probe-topic set async-inject-capture
any Reply in the document, or reply-channel set async-request-reply

AsyncAPI 3 actions describe the application the document belongs to. An operation with action: send means your service publishes, so Drift captures.

Mode preconditions are validated before Drift contacts the broker. async-inject-capture requires a probe-topic. async-request-reply requires either a reply in the document or a reply-channel parameter.

See AsyncAPI Execution Modes.

Parameters

Parameter Type Purpose
payload map The message payload Drift publishes
headers map Message headers Drift sets on publish
correlation-id string Identifies the message for this test
timeout-ms integer The capture window in milliseconds. Defaults to 30000.
probe-topic string Selects async-inject-capture and names the topic to capture from
execution-mode string Overrides the automatic mode selection
reply-channel string Names a reply channel when the document does not declare one

Transport plugins accept additional parameters of their own.

Connection Precedence

Priority Source
1 (highest) Test case or global test data
2 Plugin configuration
3 (lowest) The servers block in the AsyncAPI document

Drift applies this precedence once during planning and reuses the resolved values for the rest of the operation.

Validation

Messages Drift captures - in async-observe, async-inject-capture, and async-request-reply - are validated against the message payload schema, and against the headers schema where one is defined. Values in your expected block are compared in addition to schema validation.

Messages Drift publishes are validated against the message schema before they are sent, so a malformed test case fails before it reaches the broker.

Probe output in async-inject is compared against your expected block only. The probe result is not described in the AsyncAPI document, so there is no schema to validate against.

Probe topic messages in async-inject-capture are parsed as JSON and compared against expected without schema validation, for the same reason.

Probe topic messages in async-inject-capture are parsed as JSON and compared against expected without schema validation, for the same reason.

Limitations

  • Drift verifies one declared interaction at a time. It does not run multi-step choreography or scenario sequences.

  • Drift requires a real, running broker. There is no mock or in-memory transport.

  • Reply flows must stay on the same transport. Cross-transport replies are not supported.

  • Drift does not verify message ordering, delivery guarantees, retry behavior, or dead-letter handling.

  • Not every AsyncAPI protocol or binding is supported. See the transport plugin pages.

See Also

Was this page helpful?