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 storage dependencies.

Installation

npm install fauxqs

Usage

Running the server

npx fauxqs

The server starts on port 4566 (same as LocalStack) and handles both SQS and SNS on a single endpoint.

Override the port with the FAUXQS_PORT environment variable:

FAUXQS_PORT=3000 npx fauxqs

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:4566",
  region: "us-east-1",
  credentials: { accessKeyId: "test", secretAccessKey: "test" },
});

const snsClient = new SNSClient({
  endpoint: "http://localhost:4566",
  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({ port: 4566, logger: false });

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

// point your SDK clients at server.address

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

Pass port: 0 to let the OS assign a random available port (useful in tests).

Configurable queue URL host

By default, queue URLs use the request's Host header (e.g., http://127.0.0.1:4566/000000000000/myQueue). To match the AWS-style sqs.<region>.<host> format, pass the host option:

import { startFauxqs } from "fauxqs";

const server = await startFauxqs({ port: 4566, host: "localhost" });
// Queue URLs: http://sqs.us-east-1.localhost:4566/000000000000/myQueue

This also works with buildApp:

import { buildApp } from "fauxqs";

const app = buildApp({ host: "localhost" });

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
• Message size validation — rejects messages exceeding 1 MiB (1,048,576 bytes)
• Unicode character validation — rejects messages with characters outside the AWS-allowed set
• KMS attributes — KmsMasterKeyId and KmsDataKeyReusePeriodSeconds are accepted and stored (no actual encryption)
• 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
• Message size validation — rejects messages exceeding 256 KB (262,144 bytes)
• Topic and subscription tags
• Batch publish

Conventions

• Account ID: 000000000000
• Region: us-east-1
• Queue URL format: http://{host}:{port}/000000000000/{queueName} (or http://sqs.us-east-1.{host}:{port}/000000000000/{queueName} when host is configured)
• 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
• Cross-region or cross-account operations

License

MIT