Features - Testing AsyncAPI

How Comparison Works

When you verify a consumer contract against an AsyncAPI provider contract, Contract Testing performs these steps for each message interaction:

  1. Extracts the AsyncAPI operation ID from the interaction's comments (the operationId reference).

  2. Locates the operation in the AsyncAPI definition.

  3. Validates the interaction's message payload against each candidate message defined on that operation.

  4. Validates the interaction's metadata (such as headers) against the message's headers schema.

  5. For request/reply interactions, validates the response against the operation's reply channel messages.

An interaction matches if its payload and metadata are compatible with at least one candidate message on the operation. If multiple messages exist on the operation, Contract Testing tries each one and uses the first match.

Validation Rules

Contract Testing applies asymmetric validation semantics to message interactions, mirroring the approach used for HTTP interactions:

Scenario

Rule

Sender

The message payload must match the schema exactly. All required fields must be present, and no extra fields are allowed.

Receiver

The message payload may be a valid subset of the schema. Required fields from the schema must be present, but the provider may ignore extra fields in the message.

Channel/Topic name

The channel name or topic name in the binding must match the name specified in the interaction. For example, a Kafka topic name or SQS queue name must match exactly.

Content type

The content type must be JSON.

Note: Binding information is checked by name matching only. Binding-specific behaviour such as partitions, security policies, or schema registry validation is not performed.

Result Codes

The following result codes are specific to message interaction verification:

Result Code

Type

Meaning

Typical Fix

message.matched

Info

The message interaction passed verification.

No action needed.

message.no.match

Error

No candidate message on the operation is compatible with the interaction. Check the per-candidate failure details in the result to see why each candidate was rejected.

Adjust the interaction payload or metadata to match one of the messages defined on the operation, or update the AsyncAPI definition to include a matching message.

message.reply.missing

Error

The interaction defines a response, but the AsyncAPI operation does not include a reply block.

Either add a reply block to the AsyncAPI operation, or remove the response from the interaction if the operation should not reply.

message.response.missing

Warning

The AsyncAPI operation includes a reply block, but the interaction does not include a response.

Add a response to the interaction, or remove the reply block from the operation if no response is needed.

(unknown operation)

Error

The operationId reference does not match any operation in the AsyncAPI definition.

Verify the operationId value in the interaction matches an operation in the definition.

(spec missing)

Error

No AsyncAPI definition has been published for this provider.

Publish an AsyncAPI definition for the provider using pactflow publish-provider-contract.

(references missing)

Error

A $ref in the AsyncAPI definition cannot be resolved.

Ensure all references within the definition resolve correctly (no external file references).

Note: When multiple candidate messages are evaluated, Contract Testing reports only the final matched/no-match result and suppresses per-candidate warnings. This keeps the results clear and actionable.

Pact Support

Message interactions require Pact Specification Version 3 (with asynchronous messages) or Pact Specification Version 4 and the Asynchronous/Messages or Synchronous/Messages interaction types:

  • Fire-and-forget messages: use Asynchronous/Messages interaction type

  • Request/reply messages: use Synchronous/Messages interaction type

Each interaction must include a reference to the AsyncAPI operation ID:

{
  "comments": {
    "references": {
      "AsyncAPI": {
        "operationId": "receiveUserEvents"
      }
    }
  }
}

In Pact JS V4, use the .reference() method:

.reference('AsyncAPI', 'operationId', 'receiveUserEvents')

Note: Pact matching rules defined in your test are ignored during AsyncAPI verification. Contract Testing validates only the payload and metadata values you provide.

Diagnosing Failed Verifications

message.no.match

No message on the AsyncAPI operation matches the consumer interaction. Check the following:

  • Verify the operationId in your test matches an operation in the AsyncAPI definition.

  • Compare the payload structure in your test with the message schema in the AsyncAPI definition. Ensure all required fields are present.

  • Check that metadata (such as headers or content type) matches the message definition.

Adjust the test payload to match the AsyncAPI schema, or update the AsyncAPI definition if the schema is incorrect.

message.reply.missing

Your test expects a response, but the AsyncAPI operation does not define a reply. Confirm whether this operation should be request/reply (with a reply block) or fire-and-forget, then either add a reply block to the AsyncAPI operation or remove the response from your test.

message.response.missing

The AsyncAPI operation defines a reply, but your test does not include a response. Verify that the operation is truly request/reply, then add a response to your test interaction to match the operation's reply block.

In this section:
© 2026
Publication date: