AsyncAPI Specification Commercial

Specmatic Async - Multi-protocol async messaging testing and mocking

Specmatic Async enables contract testing and mocking of event-driven APIs and asynchronous messages/events across multiple protocols. Test complex async integrations with a unified approach, regardless of the underlying messaging technology.

Currently, Specmatic Enterprise supports the following protocols inside the AsyncAPI specifications:

For runtime broker configuration, server references, and mock/test options, see AsyncAPI Configuration.

Typical Use-case

You want to drop a message on a specific topic/queue in a messaging platform (let's say Amazon SQS), then your application picks up the message, processes it and then then emits a updated message on another topic/queue in the same or different messaging platform (let's say Kafka). You want to verify if this flow is working correctly, the messages are adhering to your defined schemas, the correct integration/messaging pattern (fire-and-forget, request-reply, pub-sub, event-stream, etc.) is being followed and so on.

To help you verify the above with a no-code approach, Specmatic will send example messages described by AsyncAPI spec files on Amazon SQS queues, verifies the corresponding messages have reached the right Kafka topics, and generates CTRF reports for the test run.

What Specmatic does

Validates SQS → Kafka integration by running contract tests defined in the AsyncAPI spec files.
Sends messages to the configured SQS endpoint and waits for expected Kafka messages.
Generates a CTRF report at the end of the run.

Quick start

Basic run:

docker run --rm --network host -v "$(pwd):/usr/src/app" specmatic/enterprise test

Key Capabilities

Feature	Description
Multi-Protocol Support	Kafka, SQS, SNS, ActiveMQ, RabbitMQ, MQTT, Google Pub/Sub, WebSocket, AWS EventBridge and more
Cross-Protocol Messaging	Mix request/reply channels across different protocols
Contract Testing	Verify async integrations match your AsyncAPI specs
Service Mocking	Simulate downstream services for isolated testing

For Kafka contracts backed by Confluent Schema Registry, see Confluent Schema Registry.

Supported Protocol Combinations

Protocol-agnostic design supports any request/reply channel combination:

SQS → Kafka             |    Kafka → SQS    |    SNS → Kafka
Kafka → Kafka           |    SQS → SQS      |    SNS → SQS
Google Pub/Sub → SQS    |    And any other combination

Getting Started

Contract Testing

Test your async applications against AsyncAPI specifications to ensure they honor the contract.

Example: SQS to Kafka Integration

Scenario: Messages arrive on an SQS queue, your app processes them and sends replies to a Kafka topic.

Define Your AsyncAPI Specification

Create spec/order-service.yaml:

spec/order-service.yaml
asyncapi: 3.0.0
info:
  title: Order Service SNS-SQS API
  version: 1.0.0
  description: |
    Receives order placement messages on SQS, replies on Kafka
servers:
  sqsServer:
    host: http://localhost:4566/000000000000
    protocol: sqs
    description: AWS SQS server for receiving messages
  kafkaServer:
    host: localhost:9092
    protocol: kafka
    description: Kafka broker for reply messages
channels:
  placeOrder:
    address: place-order-queue
    servers:
      - $ref: "#/servers/sqsServer"
    messages:
      placeOrderMessage:
        $ref: "#/components/messages/PlaceOrderMessage"
  wipOrder:
    address: place-order-topic
    servers:
      - $ref: "#/servers/kafkaServer"
    messages:
      wipOrderMessage:
        $ref: "#/components/messages/WipOrderMessage"
operations:
  sendOrder:
    description: Receive order on SQS, reply with WIP status on Kafka
    action: receive
    channel:
      $ref: "#/channels/placeOrder"
    messages:
      - $ref: "#/channels/placeOrder/messages/placeOrderMessage"
    reply:
      channel:
        $ref: "#/channels/wipOrder"
      messages:
        - $ref: "#/channels/wipOrder/messages/wipOrderMessage"

Configure Specmatic

Create a specmatic config file

YAML
JSON

specmatic.yaml
version: 3
systemUnderTest:
  service:
    $ref: "#/components/services/orderService"
    runOptions:
      $ref: "#/components/runOptions/orderServiceRunOptions"
components:
  sources:
    centralContractRepo:
      filesystem:
        directory: .
  services:
    orderService:
      description: Order Service
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/centralContractRepo"
            specs:
              - spec:
                  path: spec/order-service.yaml
  runOptions:
    orderServiceRunOptions:
      asyncapi:
        type: test
        servers:
          - server:
              host: <SQS_QUEUE_URL>
              protocol: sqs
              type: external
              adminCredentials:
                region: <REGION>
                aws.access.key.id: <AWS_ACCESS_KEY_ID>
                aws.secret.access.key: <AWS_SECRET_ACCESS_KEY>
          - server:
              host: <KAFKA_BROKER_URL>
              protocol: kafka
              type: external

specmatic.json
{
  "version": 3,
  "systemUnderTest": {
    "service": {
      "$ref": "#/components/services/orderService",
      "runOptions": {
        "$ref": "#/components/runOptions/orderServiceRunOptions"
      }
    }
  },
  "components": {
    "sources": {
      "centralContractRepo": {
        "filesystem": {
          "directory": "."
        }
      }
    },
    "services": {
      "orderService": {
        "description": "Order Service",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/centralContractRepo"
              },
              "specs": [
                {
                  "spec": {
                    "path": "spec/order-service.yaml"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    "runOptions": {
      "orderServiceRunOptions": {
        "asyncapi": {
          "type": "test",
          "servers": [
            {
              "server": {
                "host": "<SQS_QUEUE_URL>",
                "protocol": "sqs",
                "type": "external",
                "adminCredentials": {
                  "region": "<REGION>",
                  "aws.access.key.id": "<AWS_ACCESS_KEY_ID>",
                  "aws.secret.access.key": "<AWS_SECRET_ACCESS_KEY>"
                }
              }
            },
            {
              "server": {
                "host": "<KAFKA_BROKER_URL>",
                "protocol": "kafka",
                "type": "external"
              }
            }
          ]
        }
      }
    }
  }
}

Replace values in angle brackets (<...>) with your actual configuration.

Run Contract Tests

Start your application with its dependencies (SQS, Kafka, etc.), then run:
```
docker run --rm --network host -v "$(pwd):/usr/src/app" specmatic/enterprise test
```
This generates and executes contract tests based on your AsyncAPI specification.

Example Project: View complete working example →

Multi-protocol sample project:

Like SQS -> Kafka, if you want to try out specmatic-async on different flows like JMS -> Kafka or AMQP -> SQS, you can try out this sample project.

You can refer to the README of this sample project to understand how you can try it out with different protocols.

Service Mocking

Mock downstream async services when your application isn't ready or for integration testing.

Specmatic can start in-memory brokers for Kafka, JMS, and AMQP. Other protocols, including SQS, SNS, and Google Pub/Sub, require an external server configuration.

Create Test Examples

Create examples in spec/order-service_examples folder:

spec/order-service_examples/standard-order-sqs-kafka.json
{
  "name": "Standard_Order_SQS_Kafka",
  "receive": {
    "topic": "place-order-queue",
    "payload": {
      "orderType": "STANDARD",
      "orderId": "ORD-90001",
      "customerId": "CUST-44556",
      "items": [
        {
          "productId": "PROD-111",
          "quantity": 1,
          "price": 899.99
        },
        {
          "productId": "PROD-222",
          "quantity": 2,
          "price": 129.5
        }
      ],
      "totalAmount": 1158.99,
      "orderDate": "2025-12-09T14:20:00Z"
    },
    "headers": {
      "MessageGroupId": "order-group-9",
      "Subject": "Order Placed"
    }
  },
  "send": {
    "topic": "place-order-topic",
    "payload": {
      "orderId": "ORD-90001",
      "itemsCount": "$match(exact: 2)",
      "status": "$match(exact: WIP)",
      "processingStartedAt": "(datetime)"
    }
  }
}

Use Specmatic matchers like $match(exact: ...) and (datetime) to define flexible validation rules.

Update Configuration

Update the specmatic config file to use dependencies instead of systemUnderTest

YAML
JSON

specmatic.yaml
version: 3
dependencies:
  services:
    - service:
        $ref: "#/components/services/orderService"
        runOptions:
          $ref: "#/components/runOptions/orderServiceMockOptions"
        data:
          examples:
            - directories:
                - order-service_examples
components:
  sources:
    centralContractRepo:
      filesystem:
        directory: .
  services:
    orderService:
      description: Order Service
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/centralContractRepo"
            specs:
              - spec:
                  path: spec/order-service.yaml
  runOptions:
    orderServiceMockOptions:
      asyncapi:
        type: mock
        servers:
          - server:
              host: <SQS_QUEUE_URL>
              protocol: sqs
              type: external
              adminCredentials:
                aws.access.key.id: <AWS_ACCESS_KEY_ID>
                aws.secret.access.key: <AWS_SECRET_ACCESS_KEY>
          - server:
              host: <KAFKA_BROKER_URL>
              protocol: kafka
              type: external

specmatic.json
{
  "version": 3,
  "dependencies": {
    "services": [
      {
        "service": {
          "$ref": "#/components/services/orderService",
          "runOptions": {
            "$ref": "#/components/runOptions/orderServiceMockOptions"
          },
          "data": {
            "examples": [
              {
                "directories": [
                  "order-service_examples"
                ]
              }
            ]
          }
        }
      }
    ]
  },
  "components": {
    "sources": {
      "centralContractRepo": {
        "filesystem": {
          "directory": "."
        }
      }
    },
    "services": {
      "orderService": {
        "description": "Order Service",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/centralContractRepo"
              },
              "specs": [
                {
                  "spec": {
                    "path": "spec/order-service.yaml"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    "runOptions": {
      "orderServiceMockOptions": {
        "asyncapi": {
          "type": "mock",
          "servers": [
            {
              "server": {
                "host": "<SQS_QUEUE_URL>",
                "protocol": "sqs",
                "type": "external",
                "adminCredentials": {
                  "aws.access.key.id": "<AWS_ACCESS_KEY_ID>",
                  "aws.secret.access.key": "<AWS_SECRET_ACCESS_KEY>"
                }
              }
            },
            {
              "server": {
                "host": "<KAFKA_BROKER_URL>",
                "protocol": "kafka",
                "type": "external"
              }
            }
          ]
        }
      }
    }
  }
}

Start the Mock

docker run --rm --network host -v "$(pwd):/usr/src/app" specmatic/enterprise mock

How It Works:

✅ Valid messages matching your example trigger the defined reply
❌ Invalid messages are rejected with relevant log messages
🎯 Mock behaves exactly as defined in your AsyncAPI contract

Examples Validation

Validate your test examples against the AsyncAPI specification before using them.

Validate Examples in Default Location

For examples in <SPEC_NAME>_examples/ directory:

docker run --rm \
  -v "$(pwd):/usr/src/app" \
  specmatic/enterprise examples validate \
  --spec-file spec/order-service.yaml

Validate Examples in Custom Location

docker run --rm \
  -v "$(pwd):/usr/src/app" \
  specmatic/enterprise examples validate \
  --spec-file spec/order-service.yaml \
  --examples custom-examples

Command Reference

Test Command

Run contract tests against your application:

docker run --rm --network host -v "$(pwd):/usr/src/app" specmatic/enterprise test [OPTIONS]

Options:

--verbose, -v: Enable verbose logging (default: false)
--examples: Directory containing test examples (optional)
--overlay: Overlay file path (optional)
--reply-timeout: Maximum time in milliseconds to wait for reply messages (default: 10000)
--subscriber-readiness-wait-time: Time in milliseconds to wait for subscriber readiness (default: 0)

Virtualize Command

Start a mock server for async messaging protocols. Supports external brokers and in-memory Kafka, JMS, and AMQP brokers configured in specmatic.yaml.

docker run --rm --network host -v "$(pwd):/usr/src/app" specmatic/enterprise mock [OPTIONS]

Options:

--host: Fallback host for an in-memory broker (default: localhost)
--port: Fallback port for an in-memory broker
--log-dir: Fallback directory for in-memory broker logs
--verbose, -v: Enable verbose logging (default: false)
--overlay: Overlay file path (optional)
--examples: Directory containing test examples (optional)

The command uses each server's explicit type to connect to an external broker or start a supported in-memory broker. See AsyncAPI Configuration for precedence and migration details.

Examples Validate Command

Validate test examples against the specification:

specmatic-enterprise examples validate [OPTIONS]

Options:

--spec-file: Path to AsyncAPI specification (required)
--examples: Path to examples directory (optional)

Best Practices

1. Organize Your Specs

project/
├── spec/
│   ├── order-service.yaml
│   └── order-service_examples/
│       ├── Standard_Order_SQS_Kafka.json
│       └── Priority_Order_SQS_Kafka.json
└── specmatic.yaml

2. Use Examples Effectively

Create realistic examples that represent actual use cases
Use matchers for flexible validation ($match, (datetime), etc.)
Validate examples before using them for mocking or testing

3. Configuration Management

Use environment variables for sensitive credentials
Keep separate configs for different environments (dev, staging, prod)
Version control your AsyncAPI specs and examples

Configuration Reference

The AsyncAPI Configuration guide explains external and in-memory servers, inline and referenced servers, shared defaults, per-spec overrides, credentials, Schema Registry, and migration from inMemoryBroker.

Here is a complete test configuration using SQS and Kafka:

YAML
JSON

specmatic.yaml
version: 3
systemUnderTest:
  service:
    $ref: "#/components/services/orderService"
    runOptions:
      $ref: "#/components/runOptions/orderServiceRunOptions"
components:
  sources:
    centralContractRepo:
      filesystem:
        directory: .
  services:
    orderService:
      description: Order Service
      definitions:
        - definition:
            source:
              $ref: "#/components/sources/centralContractRepo"
            specs:
              - spec:
                  path: spec/order-service.yaml
  certificates:
    clientCertificate:
      keyStore:
        file: path/to/keystore.jks
        password: keystore-password
  runOptions:
    orderServiceRunOptions:
      asyncapi:
        type: test
        servers:
          - server:
              host: <SQS_QUEUE_URL>
              protocol: sqs
              type: external
              adminCredentials:
                region: <REGION>
                aws.access.key.id: <AWS_ACCESS_KEY_ID>
                aws.secret.access.key: <AWS_SECRET_ACCESS_KEY>
          - server:
              host: <KAFKA_BROKER_URL>
              protocol: kafka
              type: external
              adminCredentials:
                security.protocol: SASL_PLAINTEXT
                sasl.mechanism: PLAIN
                sasl.jaas.config: org.apache.kafka.common.security.plain.PlainLoginModule required username="admin" password="admin-secret";
              client:
                producer:
                  $ref: "#/components/certificates/clientCertificate"
                consumer:
                  $ref: "#/components/certificates/clientCertificate"

specmatic.json
{
  "version": 3,
  "systemUnderTest": {
    "service": {
      "$ref": "#/components/services/orderService",
      "runOptions": {
        "$ref": "#/components/runOptions/orderServiceRunOptions"
      }
    }
  },
  "components": {
    "sources": {
      "centralContractRepo": {
        "filesystem": {
          "directory": "."
        }
      }
    },
    "services": {
      "orderService": {
        "description": "Order Service",
        "definitions": [
          {
            "definition": {
              "source": {
                "$ref": "#/components/sources/centralContractRepo"
              },
              "specs": [
                {
                  "spec": {
                    "path": "spec/order-service.yaml"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    "certificates": {
      "clientCertificate": {
        "keyStore": {
          "file": "path/to/keystore.jks",
          "password": "keystore-password"
        }
      }
    },
    "runOptions": {
      "orderServiceRunOptions": {
        "asyncapi": {
          "type": "test",
          "servers": [
            {
              "server": {
                "host": "<SQS_QUEUE_URL>",
                "protocol": "sqs",
                "type": "external",
                "adminCredentials": {
                  "region": "<REGION>",
                  "aws.access.key.id": "<AWS_ACCESS_KEY_ID>",
                  "aws.secret.access.key": "<AWS_SECRET_ACCESS_KEY>"
                }
              }
            },
            {
              "server": {
                "host": "<KAFKA_BROKER_URL>",
                "protocol": "kafka",
                "type": "external",
                "adminCredentials": {
                  "security.protocol": "SASL_PLAINTEXT",
                  "sasl.mechanism": "PLAIN",
                  "sasl.jaas.config": "org.apache.kafka.common.security.plain.PlainLoginModule required username=\"admin\" password=\"admin-secret\";"
                },
                "client": {
                  "producer": {
                    "$ref": "#/components/certificates/clientCertificate"
                  },
                  "consumer": {
                    "$ref": "#/components/certificates/clientCertificate"
                  }
                }
              }
            }
          ]
        }
      }
    }
  }
}

Troubleshooting

Tests Not Running

Issue: Contract tests fail to start

Solutions:

Verify your application and dependencies (SQS, Kafka) are running
Check network connectivity with --network host
Ensure volume mounts point to correct directories

Mock Not Responding

Issue: Mock server doesn't process messages

Solutions:

Verify examples are in the correct directory (<SPEC_NAME>_examples/)
Run specmatic-enterprise examples validate to check example validity
Check logs for schema validation errors

Protocol Connection Issues

Issue: Cannot connect to SQS/Kafka/other protocols

Solutions:

Verify server URLs and credentials in specmatic.yaml
Check network accessibility to message brokers
Ensure protocol-specific dependencies are running

Typical Use-case​

What Specmatic does​

Quick start​

Key Capabilities​

Supported Protocol Combinations​

Getting Started​

Contract Testing​

Example: SQS to Kafka Integration​

Service Mocking​

Examples Validation​

Command Reference​

Test Command​

Virtualize Command​

Examples Validate Command​

Best Practices​

1. Organize Your Specs​

2. Use Examples Effectively​

3. Configuration Management​

Configuration Reference​

Troubleshooting​

Tests Not Running​

Mock Not Responding​

Protocol Connection Issues​

Additional Resources​

Typical Use-case

What Specmatic does

Quick start

Key Capabilities

Supported Protocol Combinations

Getting Started

Contract Testing

Example: SQS to Kafka Integration

Service Mocking

Examples Validation

Command Reference

Test Command

Virtualize Command

Examples Validate Command

Best Practices

1. Organize Your Specs

2. Use Examples Effectively

3. Configuration Management

Configuration Reference

Troubleshooting

Tests Not Running

Mock Not Responding

Protocol Connection Issues

Additional Resources