An AWS Emulator gives your tests a local AWS API. Running an integration test still involves several steps: start the emulator, wait until it is ready, configure the SDK endpoint and certificate, then clean up when the test exits.
awesome-emulator-cli wraps the test command you already use and manages that lifecycle. Python stays in pytest, Java in Maven, Rust in Cargo, Go in go test, and .NET in dotnet test. Node.js runs the CLI; your application stays in its native runtime.
Run a Boto3 test
The sample repository includes a Python test that writes a value to S3 and reads it back. The client uses Boto3's normal environment-based configuration—there is no endpoint or certificate path in the test:
from uuid import uuid4
import boto3
from emulator_sample.store import round_trip
def test_s3_round_trip():
s3 = boto3.client("s3")
bucket = f"sample-{uuid4().hex}"
s3.create_bucket(Bucket=bucket)
assert round_trip(s3, bucket, "hello.txt", "Hello from Python") == "Hello from Python"
With Node.js 22 or later, Docker, and Python installed, clone the sample repository and install its dependencies:
git clone https://github.com/c19yamamoto/awesome-emulator-cli-samples.git
cd awesome-emulator-cli-samples
npm ci
python -m pip install -e 'python[dev]'
Run the test through the CLI:
npx awesome-emulator run --telemetry off -- python -m pytest -q python/tests
--telemetry off disables AWS Emulator telemetry for this run.
run starts the emulator in Docker, waits for it to be healthy, provides the endpoint, emulator-generated credentials, region, and CA settings to pytest, then stops the emulator when pytest exits. The emulator keeps resources in memory, so each run starts with clean state. The first run downloads and verifies the emulator package and builds its image; later runs reuse it.
The CLI also removes inherited AWS credentials, profiles, and service endpoint overrides from the child environment. This keeps a developer's host AWS settings from silently redirecting the test. The CLI itself has no production npm dependencies; Python and Boto3 remain the test project's dependencies.
Use the same wrapper across SDKs
The sample repository has working examples and GitHub Actions workflows for JavaScript, Python, Go, Java, Rust, and .NET. The command shape stays the same: awesome-emulator run ... -- <your-test-command>. JavaScript runs with node --test, Python with pytest, Go with go test, Java with Maven, Rust with Cargo, and .NET with dotnet test. Java, Rust, and .NET can pass --sdk to add their language-specific certificate settings.
For workflows that seed data and test in separate steps, named sessions let the CLI keep track of the emulator lifecycle. With an initializer script of your own:
npx awesome-emulator up --session ci --init -- python scripts/seed.py
npx awesome-emulator exec --session ci -- python -m pytest -q python/tests
npx awesome-emulator down --session ci
In CI, run down in an always-run cleanup step so the session also stops after a test failure.
No AWS account or real credentials are needed for these examples. For SDK-specific options and the full language matrix, see the SDK configuration guide and sample repository.
Know what the emulator covers
AWS Emulator is for building and testing. Fidelity varies by service and feature, and the emulator does not evaluate IAM policies the way AWS does. Check the limitations and fidelity scores for the APIs you use. Keep tests against AWS for behavior and security controls the emulator does not cover.
awesome-emulator-cli is an independent project and is not affiliated with or endorsed by Amazon Web Services.
Top comments (0)