awesome-emulator-cli 0.5.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -93
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
<img src="./assets/social-preview-v2.png" alt="Awesome Emulator CLI — Local emulator testing for AWS SDKs" width="100%">
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
A Node.js CLI that manages AWS Emulator in Docker and passes its connection settings to your test command. Your tests can use any AWS SDK language; they do not need to run in Node.js.
|
|
8
8
|
|
|
9
9
|
This is an independent project and is not affiliated with or endorsed by Amazon Web Services.
|
|
10
10
|
|
|
@@ -14,106 +14,36 @@ This is an independent project and is not affiliated with or endorsed by Amazon
|
|
|
14
14
|
- Docker Engine or Docker Desktop
|
|
15
15
|
- x86_64/amd64 or ARM64/aarch64
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
On first use, Docker downloads the selected AWS Emulator RPM and signature, verifies the signature, and builds an image. The image is reused on later runs. To prepare it before tests start, run `npx awesome-emulator prepare`; use `--version` or `AWS_EMULATOR_VERSION` to select a release.
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
Prepare the image ahead of the first test run with:
|
|
22
|
-
|
|
23
|
-
```sh
|
|
24
|
-
npx awesome-emulator prepare
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
This builds or reuses the same versioned image as `start` and `run`, without starting a container or creating emulator state files. It can be run during CI setup or alongside other independent setup work so image construction does not delay the first test command. Pass `--version` or set `AWS_EMULATOR_VERSION` when you want to prepare a specific release.
|
|
28
|
-
|
|
29
|
-
## Run a test command
|
|
19
|
+
## Run tests
|
|
30
20
|
|
|
31
21
|
```sh
|
|
32
22
|
npm install --save-dev awesome-emulator-cli
|
|
33
23
|
npx awesome-emulator run -- npm test
|
|
34
24
|
```
|
|
35
25
|
|
|
36
|
-
`run` starts the emulator, supplies
|
|
37
|
-
|
|
38
|
-
Set the child's default AWS region with `--region`:
|
|
26
|
+
`run` starts the emulator, supplies its endpoint and TLS settings to the child process, then stops the container. Set the child's default region with `--region`:
|
|
39
27
|
|
|
40
28
|
```sh
|
|
41
29
|
npx awesome-emulator run --region ap-northeast-1 -- npm test
|
|
42
30
|
```
|
|
43
31
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
### Run non-Node projects
|
|
47
|
-
|
|
48
|
-
You can run an existing project command even when the project has no `package.json`. Use `npm exec` to download the CLI for the run:
|
|
32
|
+
Both `AWS_REGION` and `AWS_DEFAULT_REGION` default to `us-east-1`. An explicit region on an SDK client still takes precedence.
|
|
49
33
|
|
|
50
|
-
|
|
51
|
-
npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run -- python -m pytest
|
|
52
|
-
```
|
|
34
|
+
The CLI removes inherited AWS credentials, profiles, and service endpoints from the child environment. Credentials or endpoints explicitly set in project or build configuration still need to target the emulator. Commands run without a shell by default; on Windows, `.cmd` and `.bat` commands need `--shell`, which should only be used with trusted arguments.
|
|
53
35
|
|
|
54
|
-
The
|
|
36
|
+
The CLI can run commands from projects without a `package.json` too. For example, run Python tests with:
|
|
55
37
|
|
|
56
38
|
```sh
|
|
57
|
-
# AWS CLI v2, Boto3, and AWS SDK for Go v2 use AWS_CA_BUNDLE automatically.
|
|
58
|
-
npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run -- aws sts get-caller-identity
|
|
59
39
|
npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run -- python -m pytest
|
|
60
|
-
npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run -- go test ./...
|
|
61
|
-
|
|
62
|
-
# AWS SDK for JavaScript v3 uses NODE_EXTRA_CA_CERTS, which the CLI sets by default.
|
|
63
|
-
npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run -- npm test
|
|
64
|
-
|
|
65
|
-
# Java, Rust, and .NET need an additional TLS setting.
|
|
66
|
-
npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run --sdk java-v2 -- ./mvnw -B -o test
|
|
67
|
-
npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run --sdk rust -- cargo test --offline
|
|
68
|
-
npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run --sdk dotnet -- dotnet test --no-restore
|
|
69
40
|
```
|
|
70
41
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
The repository runs an integration smoke check for AWS CLI v2, Boto3, AWS SDK for JavaScript v3, Java 2.x, Go v2, Rust, and .NET. It verifies that each client reaches the emulator's STS endpoint with TLS enabled and receives the emulator account ID.
|
|
74
|
-
|
|
75
|
-
The common child environment sets `AWS_ENDPOINT_URL`, the emulator credentials and config files, `AWS_CA_BUNDLE`, and the region. The CLI removes inherited credential variables, profile selectors, and service-specific endpoint variables so those host environment settings cannot redirect or authenticate the test. `AWS_DISABLE_HOST_PREFIX_INJECTION` is enabled for SDKs that otherwise rewrite the local host. The wrapper manages inherited environment and JVM option variables; project code or build configuration that explicitly sets credentials or endpoints must be configured for the emulator.
|
|
76
|
-
|
|
77
|
-
Use `--sdk` only when a process needs SDK-specific TLS configuration. It can be repeated when one command runs more than one SDK:
|
|
42
|
+
The same pattern works with AWS CLI, Go, Java, Rust, and .NET projects. Use `--sdk` when a command needs SDK-specific TLS settings; see the [SDK configuration guide](./docs/sdk-configuration.md).
|
|
78
43
|
|
|
79
|
-
|
|
80
|
-
| --- | --- |
|
|
81
|
-
| AWS CLI v2, Boto3, AWS SDK for Go v2 | `AWS_CA_BUNDLE` |
|
|
82
|
-
| AWS SDK for JavaScript v3 | `NODE_EXTRA_CA_CERTS` |
|
|
83
|
-
| AWS SDK for Java 2.x | `--sdk java-v2` adds the emulator `truststore.p12` to `JAVA_TOOL_OPTIONS` |
|
|
84
|
-
| AWS SDK for Rust | `--sdk rust` sets `SSL_CERT_FILE` to `ca.pem` |
|
|
85
|
-
| AWS SDK for .NET | `--sdk dotnet` sets `SSL_CERT_FILE` to `ca.pem` |
|
|
44
|
+
## Reuse the emulator across commands
|
|
86
45
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
The AWS SDK for Java gives JVM system properties precedence over environment variables. When `--sdk java-v2` is selected, the CLI checks inherited `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, `_JAVA_OPTIONS`, `JAVA_OPTS`, `MAVEN_OPTS`, `GRADLE_OPTS`, `ANT_OPTS`, and `SBT_OPTS` values and rejects AWS credential, profile, or endpoint properties and `@argument-file` references so inherited JVM options cannot bypass the emulator settings.
|
|
90
|
-
|
|
91
|
-
`AWS_CA_BUNDLE` and `SSL_CERT_FILE` replace the default CA bundle for SDKs that read them. If the same process must contact other HTTPS services, create a combined bundle with the emulator CA and the roots it needs. `NODE_EXTRA_CA_CERTS` is additive to Node.js's default trust roots.
|
|
92
|
-
|
|
93
|
-
Child commands run without a shell by default, so each argument is passed as data. On Windows, `.cmd` and `.bat` launchers such as `npm`, and shell built-ins such as `echo` and `dir`, require an explicit shell opt-in:
|
|
94
|
-
|
|
95
|
-
```sh
|
|
96
|
-
npx awesome-emulator run --shell -- npm test
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
Use `--shell` only with trusted command and argument values. Shell metacharacters are interpreted in this mode. Node.js API callers can opt in with `runWithEmulator(command, args, { shell: true })` under the same restriction.
|
|
100
|
-
|
|
101
|
-
## Reuse an emulator across commands
|
|
102
|
-
|
|
103
|
-
Use a named session when setup and tests run in separate commands or CI steps. The session metadata is stored under `~/.aws/emulator/sessions/` with restrictive file permissions on Unix systems; it contains container and connection details, not credential values. `exec` supplies the same emulator environment as `run` and can be called repeatedly:
|
|
104
|
-
|
|
105
|
-
```sh
|
|
106
|
-
npx awesome-emulator up --session ci-tests --port 0
|
|
107
|
-
npx awesome-emulator exec --session ci-tests -- npm run seed
|
|
108
|
-
npx awesome-emulator exec --session ci-tests -- npm test
|
|
109
|
-
npx awesome-emulator down --session ci-tests
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
In CI, put the final `down` command in an always-run cleanup step so the container is removed even when a test step fails. Each CI job should use its own session name. `up` prints the connection settings as JSON; it does not print the container ID or credential values.
|
|
113
|
-
|
|
114
|
-
Persistent sessions use `ps` on Unix or Windows PowerShell on Windows to distinguish an active startup from an abandoned session record.
|
|
115
|
-
|
|
116
|
-
Run a one-time seed or setup command after the emulator becomes healthy with `--init`. The initializer receives the same emulator environment as `exec`; a non-zero exit makes `up` fail and stops the session. Initializer stdout is sent to stderr so the JSON printed by `up` remains machine-readable:
|
|
46
|
+
Use a named session when setup and tests run as separate commands or CI steps:
|
|
117
47
|
|
|
118
48
|
```sh
|
|
119
49
|
npx awesome-emulator up --session ci-tests --init -- node scripts/seed-emulator.js
|
|
@@ -121,11 +51,13 @@ npx awesome-emulator exec --session ci-tests -- npm test
|
|
|
121
51
|
npx awesome-emulator down --session ci-tests
|
|
122
52
|
```
|
|
123
53
|
|
|
124
|
-
Initializer
|
|
54
|
+
`--init` runs once after the emulator is healthy. If it fails, `up` stops the container and exits with an error. Initializer output goes to stderr so `up`'s JSON output stays machine-readable. Use `down` in an always-run CI cleanup step to stop the session after failures.
|
|
55
|
+
|
|
56
|
+
Session metadata is stored under `~/.aws/emulator/sessions/` (Windows: `%USERPROFILE%\.aws\emulator\sessions\`) and contains connection details, not credential values.
|
|
125
57
|
|
|
126
58
|
## Use from Node.js
|
|
127
59
|
|
|
128
|
-
Use the API when
|
|
60
|
+
Use the API when a test harness needs to control the emulator directly:
|
|
129
61
|
|
|
130
62
|
```js
|
|
131
63
|
import { startEmulator } from "awesome-emulator-cli";
|
|
@@ -138,24 +70,18 @@ try {
|
|
|
138
70
|
}
|
|
139
71
|
```
|
|
140
72
|
|
|
141
|
-
Pass an `AbortSignal` as `signal` to cancel image building or startup.
|
|
73
|
+
Pass an `AbortSignal` as `signal` to cancel image building or startup. For an already-running Node.js process, configure the AWS SDK's HTTPS handler with `emulator.caFile`; `NODE_EXTRA_CA_CERTS` is only read when Node.js starts.
|
|
142
74
|
|
|
143
75
|
## Local files and telemetry
|
|
144
76
|
|
|
145
|
-
The emulator
|
|
146
|
-
|
|
147
|
-
Telemetry is on by default. AWS says it collects aggregate usage and error data, not requests, responses, code, credentials, or personal data. Turn it off for a run with:
|
|
148
|
-
|
|
149
|
-
```sh
|
|
150
|
-
npx awesome-emulator run --telemetry off -- npm test
|
|
151
|
-
```
|
|
77
|
+
The emulator stores its config, credentials, and CA certificate under `~/.aws/emulator/<port>/` (Windows: `%USERPROFILE%\.aws\emulator\<port>\`). Resources stay in memory and are removed when the container stops.
|
|
152
78
|
|
|
153
|
-
|
|
79
|
+
Telemetry is on by default. Turn it off for a run with `--telemetry off`. See [AWS Emulator telemetry details](https://docs.aws.amazon.com/emulator/latest/userguide/telemetry.html) for what it collects.
|
|
154
80
|
|
|
155
81
|
AWS Emulator is for building and testing. Do not use it for production workloads or security testing. See the [official limitations](https://docs.aws.amazon.com/emulator/latest/userguide/) and [security guidance](https://docs.aws.amazon.com/emulator/latest/userguide/security.html).
|
|
156
82
|
|
|
157
|
-
See [CONTRIBUTING.md](./CONTRIBUTING.md) to contribute and [SECURITY.md](./SECURITY.md) to report a vulnerability.
|
|
158
|
-
|
|
159
83
|
## License
|
|
160
84
|
|
|
161
85
|
MIT. See [LICENSE](./LICENSE). This license covers the wrapper; downloaded AWS Emulator binaries retain their own license and notices.
|
|
86
|
+
|
|
87
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) to contribute and [SECURITY.md](./SECURITY.md) to report a vulnerability.
|