fauxqs

Local SNS/SQS emulator for development and testing. Point your @aws-sdk/client-sqs and @aws-sdk/client-sns clients at fauxqs instead of real AWS or LocalStack.

All state is in-memory. No persistence, no external dependencies.

Installation

npm install fauxqs

Usage

Running the server

npx fauxqs

The server starts on port 3000 and handles both SQS and SNS on a single endpoint.

A health check is available at GET /health.

Configuring AWS SDK clients

Point your SDK clients at the local server:

import { SQSClient } from "@aws-sdk/client-sqs";
import { SNSClient } from "@aws-sdk/client-sns";

const sqsClient = new SQSClient({
  endpoint: "http://localhost:3000",
  region: "us-east-1",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
});

const snsClient = new SNSClient({
  endpoint: "http://localhost:3000",
  region: "us-east-1",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
});

Any credentials are accepted and never validated.

Programmatic usage

You can also embed fauxqs directly in your test suite:

import { startFauxqs } from "fauxqs";

const server = await startFauxqs({ logger: false });

console.log(server.address); // "http://127.0.0.1:12345"
console.log(server.port);    // 12345

// point your SDK clients at server.address

// clean up when done
await server.stop();

Supported API Actions

SQS

SNS

SQS Features

• Message attributes with MD5 checksums matching the AWS algorithm
• Visibility timeout — messages become invisible after receive and reappear after timeout
• Delay queues — per-queue default delay and per-message delay overrides
• Long polling — WaitTimeSeconds on ReceiveMessage blocks until messages arrive or timeout
• Dead letter queues — messages exceeding maxReceiveCount are moved to the configured DLQ
• Batch operations — SendMessageBatch, DeleteMessageBatch, ChangeMessageVisibilityBatch
• Queue tags

SNS Features

• SNS-to-SQS fan-out — publish to a topic and messages are delivered to all confirmed SQS subscriptions
• Filter policies — both MessageAttributes and MessageBody scope, supporting exact match, prefix, suffix, anything-but, numeric ranges, and exists
• Raw message delivery — configurable per subscription
• Topic and subscription tags
• Batch publish

Conventions

• Account ID: 000000000000
• Region: us-east-1
• Queue URL format: http://{host}:{port}/000000000000/{queueName}
• Queue ARN format: arn:aws:sqs:us-east-1:000000000000:{queueName}
• Topic ARN format: arn:aws:sns:us-east-1:000000000000:{topicName}

Limitations

fauxqs is designed for development and testing. It does not support:

• FIFO queues and topics
• Non-SQS SNS delivery protocols (HTTP/S, Lambda, email, SMS)
• Persistence across restarts
• Authentication or authorization
• Message size limits
• Cross-region or cross-account operations

License

MIT