How do I test an SQS consumer without LocalStack?

Record your worker once against a real queue with Keploy. It captures the receive responses with their receipt handles and the delete calls that followed, then replays them in order — with no container and no polling.

Is Keploy a LocalStack alternative for SQS?

For replay, yes. LocalStack emulates the API in a container that every job has to start. Keploy records the real service once and replays it with nothing running. Keep LocalStack for exploring unrecorded API calls.

Can Keploy make SQS tests faster?

Yes. ReceiveMessage long-polls for up to twenty seconds, which is where consumer test time goes. Recorded responses replay immediately, so there is no poll wait and no empty-receive retry.

Does Keploy capture SQS receipt handles?

Yes, and it matters: without a receipt handle there is nothing to delete, so the delete-after-processing path cannot be tested. Keploy records the real handle, so that call replays as a real exchange.

Do I need AWS credentials to replay SQS tests?

No. Replay answers from the recording without signing a request or reaching AWS, so a CI job needs no IAM role — and a test cannot accidentally send to a production queue.

Is Keploy free to use with Amazon SQS?

Yes. The Keploy CLI is open source under Apache 2.0 and free to run on any service with no seat limits. Nothing is deployed into AWS and no IAM change is required to record.

Keploy as a Amazon SQS testing framework

Keploy mocks Amazon SQS by recording the AWS SDK's HTTP traffic, capturing sent message ids, received messages with their receipt handles, and delete acknowledgements, then replaying them in tests. No LocalStack runs, no queue exists, and no credentials are needed.

Generate Amazon SQS tests free

keploy record -c "./orders-worker"

18.4K+

1.2M+300M+mocks createdSlack

What Keploy gives a Amazon SQS team

Captured at the SQS HTTP API

The AWS SDK talks to SQS over HTTPS, so Keploy records the real exchange — message bodies, attributes, receipt handles, and the long-poll response shape included.

Below every AWS SDK language binding
Receipt handles preserved
Message attributes captured
Long-poll responses recorded

Try Keploy for free Explore the docs

The problem

Why Amazon SQS integration tests slow teams down

The friction is rarely the assertions. It is everything around them — spinning up dependencies, keeping mocks honest, and repairing tests after every refactor.

Book a call Explore the docs

Three ways to do it

Testing Amazon SQS: by hand, with LocalStack SQS, or with Keploy

LocalStack gives a working SQS API in a container and leaves every consumer test long-polling. Keploy records the real service once and replays it instantly.

By hand

LocalStack SQS

With Keploy

Select any row for the full comparison, with code.

Get started Book a call

Same coverage, three costs

What you write for Amazon SQS vs what Keploy records

All three produce the same assertion. Only the third still passes after the next refactor without anyone editing it.

By hand2–4 hours

fake_queue.py

hand-written

# Hand-written fake: no visibility timeout, no receipt handles.

class FakeQueue:

def __init__(self):

self.sent = []

def send(self, body, attributes=None):

# No message id, no marshalling, no queue attributes.

self.sent.append(body)

return {"MessageId": "fake"}

def receive(self, max_messages=1):

# No receipt handle, so the delete path is untestable.

return [{"Body": self.sent.pop(0)}] if self.sent else []

Without receipt handles there is nothing to delete, so the delete-after-processing path — where duplicate processing bugs live — cannot be tested.

LocalStack SQS1–2 hours

test_worker_localstack.py

tool-assisted

# LocalStack SQS: a container emulating the API.

import boto3, pytest

from testcontainers.localstack import LocalStackContainer

@pytest.fixture(scope="session")

def sqs():

with LocalStackContainer("localstack/localstack:3") as ls:

client = boto3.client("sqs", endpoint_url=ls.get_url())

client.create_queue(QueueName="orders")

yield client

def test_worker_processes_an_order(sqs):

url = sqs.get_queue_url(QueueName="orders")["QueueUrl"]

sqs.send_message(QueueUrl=url, MessageBody='{"id":"ord_1"}')

# Long polling: this is where the time goes.

msgs = sqs.receive_message(QueueUrl=url, WaitTimeSeconds=5)

assert Worker().handle(msgs["Messages"][0]) == "CONFIRMED"

Real API shape and receipt handles — and it needs a LocalStack container, a queue, and a five-second poll before the assertion.

With Keploy~5 minutes

mocks.yaml

auto-generated

# Recorded with: keploy record -c './orders-worker'

# The SQS exchange, captured at the HTTP API layer.

version: api.keploy.io/v1beta1

kind: Http

name: mock-3

spec:

request:

method: POST

url: https://queue.example.com/123456789012/orders

body: 'Action=ReceiveMessage&MaxNumberOfMessages=1&WaitTimeSeconds=20'

response:

status_code: 200

body:

Messages:

- MessageId: "b1f0-4c2a"

# The real handle, so the delete call replays too.

ReceiptHandle: "AQEB6nR8..."

Body: '{"id":"ord_1","state":"NEW"}'

MessageAttributes:

traceId: { StringValue: "9fk2mq", DataType: "String" }

The receipt handle is recorded, so the delete-after-processing call replays as a real exchange rather than being skipped.

Times are estimates for authoring one endpoint’s coverage from scratch, not measurements.

Explore the docs Request a trial

Keploy vs the alternatives

Amazon SQS testing tools, compared

The options a team on message brokers actually reaches for, and where each one genuinely wins. Select a row for the full comparison.

Keploy

Testcontainers

Embedded Kafka

MockConsumer / MockProducer

LocalStack

Postman

SmartBear ReadyAPI

Best in classStrongPartialNot covered

Assessments reflect each tool’s documented behaviour, not benchmark measurements.

Request a trial Book a call

How it works

Record your Amazon SQS app once, replay it forever

Keploy sits below your Amazon SQS process at the network layer. It watches the calls your app already makes, then serves them back on replay so tests run with no dependencies attached.

Your Amazon SQS appGET/api/v1/orders/{id}200

RecordingKeploy proxyeBPF · userspace

Pythonboto3 and aioboto3

Goaws-sdk-go-v2 sqs

Javathe AWS SDK v2 SqsClient and Spring Cloud AWS

Node.js@aws-sdk/client-sqs

+2 more Amazon SQS clients

An example shape of a captured call. Your own endpoints and dependencies come from your real traffic, so nothing here has to be written by hand.

Try Keploy for free Request a trial

Mock coverage

Amazon SQS clients Keploy records, driver by driver

Keploy captures Amazon SQS at the wire protocol, so 4 of these 6 clients need no adapter, no test double, and no Amazon SQS instance in CI.

Explore the docs Book a call

Quick start

Your first Amazon SQS test suite in under five minutes

Every command below runs against your existing Amazon SQS service. Nothing in your source tree changes.

1
1Install the Keploy CLI
A single binary. It needs a Linux kernel with eBPF support, or Docker on macOS and Windows — and it adds nothing to your project's dependencies.
curl -sSL https://keploy.io/install.sh | bash
2
2Record your service
Pass the command you already use to start the app. Keploy runs it and watches every socket it opens.
keploy record -c "./orders-worker"
3
3Exercise the paths you care about
Send a message to your development queue and let the worker process it, so the receive, the processing, and the delete are all recorded.
aws sqs send-message --queue-url $QUEUE_URL --message-body '{"id":"ord_1"}'
4
4Replay in CI
Replay serves the recorded dependency responses, so the job needs no service containers and no Docker daemon.
keploy test -c "./orders-worker" --delay 8