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

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.

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.