Skip to main content
Swagger
All documentation pages

AWS Messaging Plugin (SNS and SQS)

The AWS Messaging plugin gives Drift the ability to publish to Amazon SNS topics and to publish to and consume from Amazon SQS queues. It is used alongside the AsyncAPI plugin to verify message-based APIs whose AsyncAPI document declares the sns or sqs protocol.

Drift connects to the real service and exchanges real messages, whether that is AWS itself or a local emulator such as LocalStack.

Property Value
Plugin name aws-messaging
Purpose Amazon SNS and SQS transport for AsyncAPI operations
Protocols sns, sqs
Used with asyncapi, json
Supports Asynchronous interactions only

Enabling the Plugin

plugins:
  - name: asyncapi
  - name: aws-messaging
  - name: json

Use aws-messaging in place of the kafka plugin. One plugin covers both SNS and SQS, and Drift selects the right service per operation.

Supported Execution Modes

SNS and SQS support asynchronous interactions only - fire-and-forget flows where a message travels one way.

Mode Supported What Drift does
async-observe Yes Consumes from the queue and captures the message your service publishes
async-inject Yes Publishes the message, then runs your probe
async-inject-capture Yes Subscribes to a probe queue, publishes, then captures the harness result
async-request-reply No Not available on SNS or SQS

Choosing Between SNS and SQS

Drift determines the service per operation from the channel address, falling back to the server protocol.

Channel address Service
Starts with arn:aws:sns: SNS
Starts with arn:aws:sqs: SQS
An SQS queue URL SQS
Neither, with protocol: sns or protocol: sqs on the server Taken from the protocol

Drift can both publish and consume on either service, so all three asynchronous execution modes are available whichever one your AsyncAPI document declares.

Channel Addresses

Use an ARN or an SQS queue URL as the AsyncAPI channel address:

channels:
  inventoryAdjusted:
    address: arn:aws:sqs:us-east-1:123456789012:inventory-adjusted

  orderNotifications:
    address: arn:aws:sns:us-east-1:123456789012:order-notifications
servers:
  aws:
    host: sqs.us-east-1.amazonaws.com
    protocol: sqs

Credentials

Drift reads AWS credentials from standard environment variables and signs every request with SigV4.

Variable Required Purpose
AWS_ACCESS_KEY_ID Yes Access key
AWS_SECRET_ACCESS_KEY Yes Secret key
AWS_SESSION_TOKEN No Session token for temporary credentials
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..."      # only for temporary credentials

drift verify -f drift/inventory.testcases.yaml

Drift fails with a clear message if AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY is not set.

Do not commit credentials to your test case files. Use environment variables in local development and your CI system’s secret store in pipelines. For general Drift authentication options, see Configuring Authentication.

Region Resolution

Drift resolves the region in this order. The first match wins.

Priority Source Example
1 (highest) The region test case parameter region: eu-west-2
2 Parsed from the server host sqs.us-east-1.amazonaws.com → us-east-1
3 AWS_REGION, then AWS_DEFAULT_REGION export AWS_REGION=eu-west-2
4 (lowest) Built-in default us-east-1
parameters:
  region: eu-west-2

Overriding the Endpoint

Set an aws.endpoint-url parameter to send requests somewhere other than the public AWS endpoint. This is how you run against LocalStack or another emulator.

parameters:
  aws:
    endpoint-url: http://localhost:4566
  region: us-east-1

When no override is given, Drift builds the endpoint from the service and region as https://<service>.<region>.amazonaws.com.

Running Against LocalStack

LocalStack is the recommended local setup. It is fast, disposable, and costs nothing.

services:
  localstack:
    image: localstack/localstack:latest
    ports:
      - "4566:4566"
    environment:
      SERVICES: sqs,sns
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_REGION=us-east-1

aws --endpoint-url=http://localhost:4566 sqs create-queue \
  --queue-name inventory-adjusted
parameters:
  aws:
    endpoint-url: http://localhost:4566

Correlation

Drift carries the correlation identifier as a message attribute on publish, and filters captured messages by that attribute.

Declare the location in your AsyncAPI message. This is required - it is what enables correlation.

components:
  messages:
    inventoryAdjusted:
      correlationId:
        location: "$message.header#/correlation-id"

The value is optional. Drift takes it from the AsyncAPI document, then from the correlation-id parameter, and generates a UUID when neither supplies one.

parameters:
  correlation-id: receive-inventory-adjusted-001

Set the value yourself when a probe command or an expectation needs the same identifier. Where you do set it, give each operation a distinct value.

Capture Behavior

Drift captures from SQS using long polling, which keeps latency low without busy-waiting.

Setting Where Default Purpose
timeout-ms Test case parameter 30000 How long Drift waits for a matching message
poll-interval-ms Plugin configuration 500 Interval between receive attempts
parameters:
  timeout-ms: 10000

Allow more time than you would for a local Kafka broker. Network round trips to AWS add latency, and SQS visibility behavior can delay delivery.

Creating Queues and Topics

Drift does not create queues or topics. Create every queue, topic, and probe queue in your AsyncAPI document before the run, using the AWS CLI, your infrastructure-as-code tool, or LocalStack setup scripts.

Limitations

  • Request/reply is not supported. Use Kafka for those interactions.

  • Drift does not create queues or topics.

  • Drift captures the first message matching the correlation ID. It does not verify ordering, including FIFO queue ordering guarantees.

  • Drift does not verify visibility timeouts, dead-letter queue routing, redrive policies, or retry behavior.

  • Drift does not verify SNS subscription filter policies.

Troubleshooting

Symptom Likely cause
AWS_ACCESS_KEY_ID environment variable is not set Credentials are not exported in the shell or CI job running Drift
Signature or authorization error Wrong region. Check the resolution order above - a region parsed from the server host overrides AWS_REGION.
Requests reach AWS instead of LocalStack aws.endpoint-url is not set, or is nested incorrectly under parameters.
Queue does not exist Create the queue before the run. Drift does not create it.
Capture timeout, message was published The message attribute carries a different correlation ID, or Drift is polling a different queue
Mode error on request/reply SNS and SQS support asynchronous interactions only

See Debugging Test Cases.

See Also

Was this page helpful?