View a markdown version of this page

Versions and compatibility in AWS Emulator - AWS Emulator
Version numbersFinding and installing a specific versionSecurity fixesWhat stays compatibleHow fidelity changes affect your tests

Versions and compatibility in AWS Emulator

We aim to keep breaking changes rare, so that your tests keep working when you upgrade. This topic explains version numbers, what you can rely on, and how fidelity fixes can change your test results.

Version numbers

AWS Emulator versions use the format MAJOR.MINOR.PATCH:

  • MAJOR – Changes that can break how you start, configure, or connect to the emulator. Examples are a removed or renamed option, environment variable, or control route.

  • MINOR – New features that don’t break how you start, configure, or connect to the emulator, such as new options or new control routes.

  • PATCH – Bug fixes and fidelity fixes.

To see your version, run the following command.

aws-emulator -v

The command prints three lines:

  • Version – The version of the emulator

  • Release date – The date of the release

  • Commit – The GitHub commit for the build

Finding and installing a specific version

Packages are published under the following address. The latest packages are in the latest/ folder.

https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/

For the list of published versions, see the following file.

https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/versions.json

To install a specific version, put the version in the package file name. Replace <version> with a version from the list:

  • RPM package (x86_64) – https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/aws-emulator-<version>-1-x86_64.rpm

  • RPM package (aarch64) – https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/aws-emulator-<version>-1-aarch64.rpm

  • Debian package (amd64) – https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/aws-emulator_<version>-1_amd64.deb

  • Debian package (arm64) – https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/aws-emulator_<version>-1_arm64.deb

Install the package the same way as the latest release, as shown in To install AWS Emulator.

We recommend that you use the latest version. If a new release changes your test results, see How fidelity changes affect your tests.

Security fixes

We publish security fixes only in the latest release. Older releases don’t get fixes. To get them, upgrade to the latest release.

A security fix might need a breaking change, even within a major version. For example, an operation that works without credentials might start to need them.

What stays compatible

Within a major version, these stay the same:

  • The aws-emulator command, its options, and their default values

  • The environment variables in this guide

  • The emulator control routes, such as the health check

  • The package URLs on downloads.aws.com

  • The startup line of the log and its fields, which give the address and port that the emulator serves on

Don’t rely on the following. They can change in any release:

  • The fields in log output, other than the startup line. The emulator writes its log as JSON lines, but the rest of the log isn’t a stable interface.

  • The content of the -h help text

  • Files in the emulator’s local directories, other than the ones in this guide

  • The size and format of the credentials that the emulator generates

  • What’s in the installation package, other than the aws-emulator command and the license and notice files

How fidelity changes affect your tests

We test each release against the fidelity tests in the aws-emulator-evaluation-suite repository on GitHub. We publish the scores for each service with each release, with the version of the fidelity tests that we used. For more information, see Reading the fidelity scores.

  • Behavior that a passing fidelity test covers – Fidelity tests that pass don’t regress.

  • Behavior that no fidelity test covers – A release can fix a response so it matches AWS. If your tests relied on the earlier response, they can start to fail.

The fidelity tests don’t cover every behavior yet. We’re continuously adding new fidelity tests based on customer feedback and fidelity issues that we discover. To learn how to check which behavior they cover, see Checking whether your project works with AWS Emulator. To limit the effect of these changes:

  • If new releases change your test results, install a specific version, as described in Finding and installing a specific version. Then a new release changes your results only when you choose to upgrade. Test a new version before you upgrade.

  • Write tests that expect what AWS does, not what the emulator does today. As the emulator’s fidelity improves, it moves closer to AWS. For the APIs that matter to your app, also run your tests against AWS. For more information, see Fidelity in AWS Emulator.

If a patch release changes your test results, either the emulator now matches AWS more closely, or it’s a bug that you can report. Read the release notes on the AWS Emulator releases page on GitHub before you move to a new minor or major version.

If a release makes the emulator act differently from AWS, tell us. For more information, see Telling us about a difference.