Skip to content
Go back

What AWS Emulator lets you test before you deploy

AWS Emulator lets you test code that calls AWS without deploying it first. AWS made it generally available on November 11, 2026. It runs on your machine or in continuous integration (CI), where it accepts supported API calls from the AWS CLI and SDKs. You don’t need an AWS account to run it.

Use it to test the AWS behavior your application depends on: can it read a file from S3, reject a duplicate write in DynamoDB, or recover when SQS delivers a message twice? Run those checks on a laptop while you change the code, repeat them on pull requests, or let a coding agent test its changes without access to a live account. Coverage varies by operation, so start with the behavior you need to verify.

What runs on your machine

Point your CLI or SDK at the emulator’s local HTTPS endpoint. When a test creates a bucket, uploads a file, and reads it back, each call sees the state left by the previous one. The emulator keeps that state in memory and discards it on exit, so a fresh instance gives the next test run a clean set of resources.

The CLI is handy for creating fixtures and inspecting results. The SDK lets the application use its regular clients. AWS provides Linux packages and a Docker setup for macOS and Windows, and Rust tests can embed the emulator directly. In server mode the emulator generates its own signing credentials and local certificate. It doesn’t need access to your AWS account to serve requests.

There’s a useful distinction between configuring a service and using it. Creating an S3 bucket is a control-plane operation; uploading and reading an object are data-plane operations. A successful create call can mean the emulator accepted the configuration and recorded it. It tells you much less about whether the workload behind it will run. In one public CDK test, the emulator created an ECS service record, yet no containers started. The right test depends on which of those two outcomes the application needs.

Which workflows are worth testing

Start with the AWS operations your code calls. A broad list of services can tell you what to investigate; a passing test of the behavior you depend on tells you what to keep in the local test suite.

WorkflowA useful first testWhat to verify in real AWS
S3 and DynamoDBRead a file, store its metadata, and repeat the request. Check that a conditional write preserves the original record.Bucket and table permissions, contention, and throttling at production load.
SQS, SNS, and EventBridgeReceive a message twice, or publish one matching event and one non-matching event. Check what actually lands in the queue.Managed trigger configuration, retry and redrive behavior, and service permissions.
Lambda and Step FunctionsInvoke a simple handler or run a short workflow with an error branch. Check the exact result and state change.The deployed package, runtime dependencies, networking, and managed triggers.
CloudFormation and service setupTry a small template and inspect the resources it creates.Whether the actual stack starts and its components communicate.

There are public examples at both ends of that range. A notes app backed by S3 and DynamoDB covers save, read, overwrite, and missing notes and includes a GitHub Actions workflow. A serverless order demo exercises payment retries and inventory rollback. Its author also hit runtime and integration gaps. Copy the test idea; verify the operations on the release you plan to use.

AWS calls the match between its services and the emulator fidelity. The release scores count test cases that match AWS, including expected errors and resulting state. A service score is not the percentage of API operations implemented. List your calls, look for matching cases in the fidelity test suite, and run your own workflow against the pinned release. An unimplemented operation returns 501 Not Implemented; a successful response is a reason to check the actual state or side effect you care about.

Set up one test that can fail for a useful reason

Start the emulator, point the SDK or CLI at its loopback address, and use the generated credentials and certificate. The connection guide has the environment settings. Run setup and tests in the same isolated process, with real AWS credentials removed. Verify where requests go before allowing writes. A reported JavaScript SQS setup sent CreateQueue to the emulator but let SendMessage follow the returned queue URL to AWS. Checking only the initial endpoint would have missed that.

For a concrete example, I tested a worker that reads a file from S3 and records its metadata in DynamoDB. The queue message carries the file key and an application request ID. I let the first write succeed, then prevented the worker from acknowledging the delivery:

First delivery  → read S3 → write DynamoDB row → acknowledgement never sent
Second delivery → read S3 → find original row  → acknowledge current delivery
                                               → still one unchanged row

The second delivery had the same message ID and a new SQS receipt handle. That handle identifies a delivery and is needed to acknowledge it. The worker uses the application request ID to identify the work. A conditional write keyed by that ID left exactly one unchanged record. That verifies the worker’s response to redelivery; managed Lambda polling still needs a separate test.

Give a coding agent the same loop

AWS’s coding-agent setup skill can start the emulator, connect the SDK or CLI, and check which operations a project uses. The launch walkthrough shows a coding agent creating a DynamoDB table, writing an item, and reading it back. Give the agent an expected outcome it can assert, not merely a service it can call:

List the AWS operations this change touches. Use a fresh, pinned emulator and synthetic data. Reproduce one failure, then verify the exact state left behind. Report what passed locally and what still needs real AWS. Do not deploy.

That loop also works when the application under development happens to be an AI agent. Test the S3 or DynamoDB calls behind its tools locally. Verify model tool selection, hosted runtime behavior, and permissions in staging. Those are different tests from the ones the coding agent runs while editing the project.

There’s a second agent story in the emulator itself. AWS says agents build and maintain it: they find differences from real AWS, write tests and fixes, and send changes through a release pipeline that reruns the fidelity tests. The part worth copying is the independent check. An agent can propose the code and even write the test, but the expected behavior needs a reference outside the agent’s own implementation.

What a green local run buys you

I’d use AWS Emulator as a pull-request check for code that reads or changes AWS state. The SQS test is the reason: I could reproduce the missed acknowledgement, inspect the second delivery, and verify the exact record left behind. That is stronger evidence than a mock configured to return the response I expected, and I didn’t have to deploy the worker to get it.

Start with one assertion a caller would notice: one record after two deliveries, an unchanged item after a conflict, or a message arriving in the intended queue. Keep a small real-AWS suite for the documented limits: permissions, account and Region boundaries, and the managed behavior your application relies on. Use real infrastructure for performance tests.

For coding agents, this is a step toward a better division of work. Let them prototype, build, and verify changes against disposable resources, then hand over the evidence. Operating a live system calls for separate controls: narrowly scoped permissions, a record of what the agent did, approval for consequential changes, and a way to roll them back. A passing local test earns a staging run; it doesn’t grant production access.

The open question is how long a local test and its staging counterpart keep answering the same question. When the emulator, SDK, or service changes, which small set of workflows is worth running in both places to catch drift?


Share this post on:


Next Post
Three of Eight AI Models Solved a 6-Move Rubik's Cube