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:

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

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:
          - host: <SQS_QUEUE_URL>
            protocol: sqs
            adminCredentials:
              region: <REGION>
              aws.access.key.id: <AWS_ACCESS_KEY_ID>
              aws.secret.access.key: <AWS_SECRET_ACCESS_KEY>
          - host: <KAFKA_BROKER_URL>
            protocol: kafka

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": [
            {
              "host": "<SQS_QUEUE_URL>",
              "protocol": "sqs",
              "adminCredentials": {
                "region": "<REGION>",
                "aws.access.key.id": "<AWS_ACCESS_KEY_ID>",
                "aws.secret.access.key": "<AWS_SECRET_ACCESS_KEY>"
              }
            },
            {
              "host": "<KAFKA_BROKER_URL>",
              "protocol": "kafka"
            }
          ]
        }
      }
    }
  }
}

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.

For protocols other than Kafka (e.g., SQS, SNS, Google Pub/Sub), you must configure external brokers in specmatic.yaml. In-memory broker is currently only supported for Kafka.

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:
          - host: <SQS_QUEUE_URL>
            protocol: sqs
            adminCredentials:
              aws.access.key.id: <AWS_ACCESS_KEY_ID>
              aws.secret.access.key: <AWS_SECRET_ACCESS_KEY>
          - host: <KAFKA_BROKER_URL>
            protocol: kafka

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": [
            {
              "host": "<SQS_QUEUE_URL>",
              "protocol": "sqs",
              "adminCredentials": {
                "aws.access.key.id": "<AWS_ACCESS_KEY_ID>",
                "aws.secret.access.key": "<AWS_SECRET_ACCESS_KEY>"
              }
            },
            {
              "host": "<KAFKA_BROKER_URL>",
              "protocol": "kafka"
            }
          ]
        }
      }
    }
  }
}

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:

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/stub server for async messaging protocols. Supports both external brokers (configured in specmatic.yaml) and in-memory Kafka broker.

Aliases: stub, virtualize

specmatic-enterprise virtualize [OPTIONS]

Options:

--host: Host for in-memory Kafka broker (default: localhost)
--port: Port for in-memory Kafka broker (default: 9092)
--log-dir: Directory for in-memory Kafka broker logs (default: ./kafka-logs)
--verbose, -v: Enable verbose logging (default: false)
--overlay: Overlay file path (optional)
--examples: Directory containing test examples (optional)

The command automatically detects whether to use external brokers (if configured in specmatic.yaml) or start an in-memory Kafka broker. In-memory broker is currently only supported for Kafka.

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

Complete Configuration Structure

The specmatic.yaml file supports detailed configuration for async messaging protocols. Here's the complete structure:

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:
          - host: <SQS_QUEUE_URL>
            protocol: sqs
            adminCredentials:
              region: <REGION>
              aws.access.key.id: <AWS_ACCESS_KEY_ID>
              aws.secret.access.key: <AWS_SECRET_ACCESS_KEY>
          - host: <KAFKA_BROKER_URL>
            protocol: kafka
            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": [
            {
              "host": "<SQS_QUEUE_URL>",
              "protocol": "sqs",
              "adminCredentials": {
                "region": "<REGION>",
                "aws.access.key.id": "<AWS_ACCESS_KEY_ID>",
                "aws.secret.access.key": "<AWS_SECRET_ACCESS_KEY>"
              }
            },
            {
              "host": "<KAFKA_BROKER_URL>",
              "protocol": "kafka",
              "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"
                }
              }
            }
          ]
        }
      }
    }
  }
}

Protocol-Specific Configurations

Kafka

Basic Configuration:

servers:
  - host: localhost:9092
    protocol: kafka

With Authentication (SASL):

servers:
  - host: localhost:9092
    protocol: kafka
    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:
        basic.auth.credentials.source: USER_INFO
        basic.auth.user.info: admin:admin-secret
      consumer:
        basic.auth.credentials.source: USER_INFO
        basic.auth.user.info: admin:admin-secret

Configuration Options:

Property	Description
`host`	Kafka broker URL (e.g., `localhost:9092`)
`protocol`	Must be `kafka`
`adminCredentials`	Kafka admin client properties for topic management
`client.producer`	Standard Kafka producer properties
`client.consumer`	Standard Kafka consumer properties

The producer and consumer sections accept any standard Kafka producer and consumer configuration properties.

AWS SQS

Configuration:

servers:
  - host: http://localhost:4566/000000000000
    protocol: sqs
    adminCredentials:
      region: us-east-1
      aws.access.key.id: test
      aws.secret.access.key: test

Configuration Options:

Property	Description
`host`	SQS endpoint URL including account ID
`protocol`	Must be `sqs`
`adminCredentials.region`	AWS region (e.g., `us-east-1`)
`adminCredentials.aws.access.key.id`	AWS access key ID
`adminCredentials.aws.secret.access.key`	AWS secret access key

For LocalStack, use http://localhost:4566/000000000000. For production AWS, use the full SQS endpoint URL.

AWS EventBridge

Configuration:

servers:
  - host: http://localhost:4566/000000000000
    protocol: eventbridge
    adminCredentials:
      region: us-east-1
      aws.access.key.id: test
      aws.secret.access.key: test

Configuration Options:

Property	Description
`host`	EventBridge endpoint URL including account ID
`protocol`	Must be `eventbridge`
`adminCredentials.region`	AWS region (e.g., `us-east-1`)
`adminCredentials.aws.access.key.id`	AWS access key ID
`adminCredentials.aws.secret.access.key`	AWS secret access key

Schema Registry Configuration

Use Schema Registry to manage and validate message schemas (typically with Kafka).

Confluent Schema Registry:

config:
  schemaRegistry:
    kind: CONFLUENT
    url: http://localhost:8085
    username: admin
    password: admin-secret
  
  servers:
    - host: localhost:9092
      protocol: kafka

Configuration Options:

Property	Description
`kind`	Schema registry type (currently `CONFLUENT`)
`url`	Schema registry endpoint URL
`username`	Authentication username (optional)
`password`	Authentication password (optional)

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​

Complete Configuration Structure​

Protocol-Specific Configurations​

Kafka​

AWS SQS​

AWS EventBridge​

Schema Registry Configuration​

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

Complete Configuration Structure

Protocol-Specific Configurations

Kafka

AWS SQS

AWS EventBridge

Schema Registry Configuration

Troubleshooting

Tests Not Running

Mock Not Responding

Protocol Connection Issues

Additional Resources