AWS Emulator for .NET: Local AWS Testing, HTTPS and CI

AWS released AWS Emulator on November 11, 2026. It lets an application or CI job send supported AWS SDK or CLI requests to a local HTTPS endpoint without an AWS account. Each emulator process has isolated in-memory state and its own credentials. AWS returns HTTP 501 for operations the emulator has yet to implement.

Where does AWS Emulator fit?

Approach	What it exercises	What to check separately
Mock client	Application branches and predictable failures	HTTP, signing and service behavior
Local AWS Emulator	Real SDK request construction against implemented local API behavior	Unsupported operations and production account behavior
Other local emulator	The particular APIs and features it implements	Compatibility and licensing for the exact build
Test AWS account	Deployed service behavior, IAM and integration boundaries	Safe isolation, costs and cleanup

AWS says emulator service models are generated from published AWS API models and behavior is filled in release by release. Seeing an operation in a model is different from having an implemented operation. Check the documentation and release-specific fidelity report for the calls your app actually makes. AWS launch notice · AWS Emulator documentation.

Set up a local test

1. Use the documented Linux package on Linux, or follow the Docker workflow on Windows, macOS or Linux. For in-process embedding AWS documents a Rust path. A C# app uses the external endpoint.
2. Start the emulator using the instructions for your platform. The default Linux and Docker path listens on loopback HTTPS port 9297.
3. Read the generated config, credentials and certificate from the directory for that port. An instance restart can change those files and clears its in-memory resources.
4. Point only the development or test process at the emulator. Keep deployment profiles and credentials outside the test environment.
5. Choose a documented supported operation and validate the result before moving an entire integration suite.

Follow the platform-specific setup and SDK endpoint guide for exact setup commands and certificate handling.

The following health request uses the generated CA on the default port. A ready instance returns HTTP 200 with body ok.

curl --fail --cacert "$HOME/.aws/emulator/9297/ca.pem" https://127.0.0.1:9297/__admin/health

Test AWS calls locally.

How can an ASP.NET Core app connect?

Use the ordinary service client and point its configuration to the emulator with the documented SDK environment. For .NET, AWS specifies SSL_CERT_FILE pointing to the generated ca.pem. Put that setting and the emulator’s endpoint and credentials in a dedicated development launch environment. An application that constructs its own service client with an explicit production endpoint may override shared endpoint configuration. Check the effective endpoint before running a request.

For an inventory API backed by DynamoDB, make a test fixture that starts an isolated emulator, creates a synthetic table, and runs a read through the normal application path. If the tested operation is implemented, assert the response and verify that the resource remains visible on later calls in the same process. An independent CI job should have a separate instance and state. The lab design here follows the docs and was not executed against a running emulator.

Troubleshoot the first request

• Certificate verification fails. Use the current generated CA and the trust configuration documented for your SDK and platform. Keep HTTPS validation enabled.
• The application cannot reach localhost. If the app and emulator run in different containers, loopback addresses refer to different network namespaces. Follow the documented networking setup and keep the service confined to the test network.
• Authentication fails. Check the credentials from the current emulator run and confirm the test process did not inherit a cloud session token or deployment profile.
• HTTP 501 appears. Check implementation status. Route that case to a controlled AWS integration test if production behavior matters.
• State disappears. The launch documentation describes in-memory state. Reseed on startup.

What is the coding-agent workflow?

AWS documents an aws-emulator skill that guides a compatible agent through starting the emulator and connecting tools. Review generated commands and run them in a disposable workspace. Enforce endpoint and credential isolation outside the agent prompt. The emulator has no additional AWS service fee. Local compute, CI capacity and separately deployed AWS resources still have their usual costs.

FAQ

Does it replace a cloud integration test? Keep a cloud stage for service behavior the emulator cannot prove, such as production IAM, quotas, networking and managed integrations.

Can two test jobs share an emulator? Independent instances give each job isolated state and credentials. That avoids name collisions and accidental cross-test reads.

How does this relate to SDK retries? A local response can help exercise an application’s handling of errors, while real cloud latency and throttling still require representative tests. See ASP.NET PB’s HTTP resilience guide.