Skip to content
ES EN
Theme: automatic

AWS Emulator: Test Your Apps Against 200+ AWS Services Locally

A practical guide to using AWS Emulator locally with the CLI, an SDK, or code agents: what you need, how to connect it, and what limits to watch out for.

Software engineering

Testing against the real cloud costs money, requires an account, and becomes cumbersome when the code writer is an agent iterating non-stop. AWS Emulator is AWS's answer: a local program that serves an HTTPS endpoint with the public APIs of over 200 services, with no charges for the operations it emulates.

In this guide, we'll set up the basic flow: install it, point the CLI or an SDK to it, and check what it returns. You'll also see where it falls short, as it has documented limitations that are worth knowing before relying on it.

What you need

  • A Linux machine (RPM or Debian package, x86_64 or aarch64), or macOS/Windows with Docker.
  • The AWS CLI or an AWS SDK already installed in your project.
  • The official user guide handy for installation and setup details.
  • Tolerance for some operations responding "not implemented": it's part of the current design.
Diagram of a development laptop sending requests to a local service instead of the cloud
The idea: your code talks to a local endpoint instead of AWS.

Install and connect it

  1. Install the emulator. On Linux, there are RPM and Debian packages; on macOS and Windows, AWS documents a short Dockerfile because it doesn't publish a pre-built image.
  2. Start it and note the local HTTPS address it's listening on, as indicated in the user guide.
  3. Define the AWS_ENDPOINT_URL variable so that the CLI or SDK points to the emulator. No need to touch the application code.
  4. Create a test resource, for example a bucket or a queue, and check that the response and errors resemble those from AWS.
  5. Repeat the trial and error cycle as many times as you need: no account or bill involved.
export AWS_ENDPOINT_URL=https://localhost:PUERTO
aws s3 ls

Replace PUERTO with the port your installation uses; we're not inventing a default value because the AWS_ENDPOINT_URL reference is authoritative. If you use Rust, there's an embedded mode that runs the emulator within the test process itself and connects its HTTP client to the AWS SDK for Rust.

For code agents and fidelity checking

The project includes a skill called aws-emulator that allows an agent to start the emulator and compare a project against published fidelity tests. These tests live in the evaluation suite and, to pass, require each call to match AWS in status codes, side effects, and exact errors.

The emulator is written in Rust and is generated from the Smithy models of the APIs. According to Matthew Goldberg, it was built by agent teams that write tests, replicate them, and fix bugs, with a merge gate that reviews compilation, security, and regressions. More context is available in the article on the engineer's job.

Limits you should know

  • It does not evaluate IAM or resource-based policies: it's not for testing security.
  • It uses a single account and region per process.
  • State is in memory and disappears when the process stops.
  • It's not designed for load testing or prolonged use.
  • Unimplemented operations return HTTP 501 with the NotImplemented error.
  • CloudFormation, Terraform, and CDK support varies by service.
Tip Before adopting it, check the fidelity score of the services you actually use. Community data places S3, DynamoDB, and SQS at around two out of three tests passed, and CloudFormation below one out of five. And it doesn't replace LocalStack, Floci, or moto in permission or infrastructure-as-code workflows.
Panel with fidelity scores by service, with bars of different lengths
Fidelity is not uniform: check your service before trusting it.

The emulator is available at no additional cost and its code is published under public domain (CC0), except for third-party code in the vendor/ directory, which is Apache 2.0. Use it to iterate quickly and cheaply, and reserve the real account for validating permissions and deployments.

Original source: infoq.com

Article generated with AI.larebelion

Kernel

· Head of Technology · Spain

«Over 200 services sounds like a lot, but the fidelity score is the number that decides if you trust it.»

Comments (0)

No comments yet. You can be the first.

Write a comment