awesome-emulator-cli 0.3.0 → 0.4.0

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 CHANGED
@@ -1,10 +1,10 @@
1
1
  # Awesome Emulator CLI
2
2
 
3
3
  <p align="center">
4
- <img src="./assets/social-preview.png" alt="Awesome Emulator CLI — Local emulator testing for Node.js" width="100%">
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
- Awesome Emulator CLI for use with AWS Emulator in local tests from npm scripts or Node.js. It runs the upstream Linux package in Docker.
7
+ Awesome Emulator CLI is a Docker wrapper for AWS Emulator: it starts a local container and supplies connection settings to your test command. The CLI is distributed with Node.js, but the project under test can use any AWS SDK language and does not need to be a Node.js project.
8
8
 
9
9
  This is an independent project and is not affiliated with or endorsed by Amazon Web Services.
10
10
 
@@ -14,6 +14,8 @@ 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
+ Node.js is required to run the CLI. Your application and test project can use any language.
18
+
17
19
  On first start, Docker downloads the selected AWS Emulator RPM and its signature, verifies the signature, and builds a local image. Later starts reuse the image for that version and architecture.
18
20
 
19
21
  Prepare the image ahead of the first test run with:
@@ -33,6 +35,61 @@ npx awesome-emulator run -- npm test
33
35
 
34
36
  `run` starts the emulator, supplies the connection settings to the child process, then stops the container. Use `--version` to select a release and `--port 0` to choose a free local port. Run `npx awesome-emulator --help` for all options.
35
37
 
38
+ Set the child's default AWS region with `--region`:
39
+
40
+ ```sh
41
+ npx awesome-emulator run --region ap-northeast-1 -- npm test
42
+ ```
43
+
44
+ By default, both `AWS_REGION` and `AWS_DEFAULT_REGION` are `us-east-1`. `--region` sets both for the child command without changing the emulator endpoint. An SDK client configured with its own region continues to use that explicit region.
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:
49
+
50
+ ```sh
51
+ npm exec --yes --package=awesome-emulator-cli -- awesome-emulator run -- python -m pytest
52
+ ```
53
+
54
+ The same pattern works with other SDK projects:
55
+
56
+ ```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
+ 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
+ ```
70
+
71
+ Resolve Java, Rust, and .NET dependencies before the wrapped command when they are not already cached. For example, run `./mvnw -B dependency:go-offline`, `cargo fetch`, or `dotnet restore` before starting the emulator.
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:
78
+
79
+ | SDK | TLS configuration |
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` |
86
+
87
+ Java's `JAVA_TOOL_OPTIONS` applies to every JVM started by the child command, including Maven or Gradle and test workers. Resolve Java build dependencies before invoking `awesome-emulator run`, or use a truststore that contains both the emulator certificate and the certificates for other HTTPS hosts. The emulator truststore contains only the emulator certificate, so HTTPS calls to Maven Central, AWS, or other hosts can fail while it is active. The CLI appends to existing `JAVA_TOOL_OPTIONS`; if `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, or `_JAVA_OPTIONS` already sets `javax.net.ssl.trustStore`, it preserves that truststore. If only `javax.net.ssl.trustStoreType=PKCS12` is set, the CLI adds the emulator truststore path and preserves the type. An incompatible truststore type requires a custom truststore path. A preserved truststore must also trust the emulator. `MAVEN_OPTS` and `GRADLE_OPTS` remain in their own variables; if either sets a separate truststore, make sure the Java test JVM trusts the emulator too.
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
+
36
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:
37
94
 
38
95
  ```sh
package/dist/cli.js CHANGED
@@ -1,18 +1,22 @@
1
1
  #!/usr/bin/env node
2
- import { prepareEmulatorImage, runWithEmulator, startEmulator } from "./index.js";
2
+ import { prepareEmulatorImage, runWithEmulator, startEmulator, } from "./index.js";
3
3
  import { DEFAULT_VERSION } from "./emulator-options.js";
4
4
  import { FORWARDED_SIGNALS, getSignalExitCode } from "./signals.js";
5
+ import { DEFAULT_AWS_REGION, SUPPORTED_EMULATOR_SDKS } from "./emulator-environment.js";
5
6
  function usage() {
6
7
  console.log(`Usage:
7
8
  awesome-emulator prepare [--version <version>]
8
9
  awesome-emulator start [options]
9
- awesome-emulator run [options] [--shell] -- <command> [args...]
10
+ awesome-emulator run [options] [--region <region>] [--sdk <family>]... [--shell] -- <command> [args...]
10
11
 
11
12
  Options:
12
13
  -v, --version <version> AWS Emulator version (default: ${DEFAULT_VERSION})
13
14
  -p, --port <port> (start/run) Host port; 0 chooses an available port (default: 9297)
14
15
  -t, --telemetry <on|off> (start/run) Telemetry setting (default: on)
15
16
  --memory <limit> (start/run) Container memory limit (default: 2g)
17
+ --region <region> (run only) Default region for the child command (default: ${DEFAULT_AWS_REGION})
18
+ --sdk <family> (run only) Add SDK-specific TLS settings; repeatable
19
+ (${SUPPORTED_EMULATOR_SDKS.join(", ")})
16
20
  --shell (run only) Enable .cmd/.bat and built-ins; trusted values only
17
21
  -h, --help Show this help`);
18
22
  }
@@ -41,15 +45,33 @@ function parse(argv) {
41
45
  options.shell = true;
42
46
  continue;
43
47
  }
48
+ if (token === "--sdk") {
49
+ if (command !== "run")
50
+ throw new Error("--sdk can only be used with the run command.");
51
+ const value = argv[index + 1];
52
+ if (!value || value.startsWith("--"))
53
+ throw new Error("Missing value for --sdk");
54
+ if (!SUPPORTED_EMULATOR_SDKS.includes(value)) {
55
+ throw new Error(`Unsupported SDK: ${value}. Choose from ${SUPPORTED_EMULATOR_SDKS.join(", ")}.`);
56
+ }
57
+ options.sdks ??= [];
58
+ options.sdks.push(value);
59
+ index += 1;
60
+ continue;
61
+ }
44
62
  const optionNames = {
45
63
  "-v": "version", "--version": "version",
46
64
  "-p": "port", "--port": "port",
47
65
  "-t": "telemetry", "--telemetry": "telemetry",
48
66
  "--memory": "memory",
67
+ "--region": "region",
49
68
  };
50
69
  const key = optionNames[token];
51
70
  if (!key)
52
71
  throw new Error(`Unknown option: ${token}`);
72
+ if (key === "region" && command !== "run") {
73
+ throw new Error("--region can only be used with the run command.");
74
+ }
53
75
  if (command === "prepare" && key !== "version") {
54
76
  throw new Error(`${token} can only be used with the start or run command.`);
55
77
  }
@@ -7,6 +7,15 @@ export type EmulatorEnvironment = {
7
7
  AWS_REGION: string;
8
8
  AWS_DEFAULT_REGION: string;
9
9
  NODE_EXTRA_CA_CERTS: string;
10
+ AWS_DISABLE_HOST_PREFIX_INJECTION: "true";
11
+ };
12
+ export declare const SUPPORTED_EMULATOR_SDKS: readonly ["java-v2", "rust", "dotnet"];
13
+ export type EmulatorSdk = typeof SUPPORTED_EMULATOR_SDKS[number];
14
+ export declare const DEFAULT_AWS_REGION = "us-east-1";
15
+ export type ChildEnvironmentOptions = {
16
+ sdks?: readonly EmulatorSdk[];
17
+ region?: string;
18
+ platform?: NodeJS.Platform;
10
19
  };
11
20
  export type EmulatorConnectionSettings = {
12
21
  endpointUrl: string;
@@ -16,5 +25,7 @@ export type EmulatorConnectionSettings = {
16
25
  caFile: string;
17
26
  environment: EmulatorEnvironment;
18
27
  };
28
+ export declare function normalizeEmulatorSdks(sdks?: readonly string[]): EmulatorSdk[];
29
+ export declare function resolveAwsRegion(region: string | undefined, defaultRegion?: string): string;
19
30
  export declare function createEmulatorConnectionSettings(port: number, stateDirectory: string): EmulatorConnectionSettings;
20
- export declare function createChildEnvironment(parentEnvironment: NodeJS.ProcessEnv, emulatorEnvironment: EmulatorEnvironment): NodeJS.ProcessEnv;
31
+ export declare function createChildEnvironment(parentEnvironment: NodeJS.ProcessEnv, emulatorEnvironment: EmulatorEnvironment, options?: ChildEnvironmentOptions): NodeJS.ProcessEnv;
@@ -1,18 +1,60 @@
1
1
  import path from "node:path";
2
+ export const SUPPORTED_EMULATOR_SDKS = [
3
+ "java-v2",
4
+ "rust",
5
+ "dotnet",
6
+ ];
7
+ export const DEFAULT_AWS_REGION = "us-east-1";
2
8
  const AWS_CREDENTIAL_ENVIRONMENT_KEYS = [
9
+ "AWS_ACCESS_KEY",
3
10
  "AWS_ACCESS_KEY_ID",
11
+ "AWS_SECRET_KEY",
4
12
  "AWS_SECRET_ACCESS_KEY",
13
+ "AWS_SECURITY_TOKEN",
5
14
  "AWS_SESSION_TOKEN",
6
15
  "AWS_PROFILE",
7
16
  "AWS_DEFAULT_PROFILE",
8
17
  "AWS_ROLE_ARN",
9
18
  "AWS_WEB_IDENTITY_TOKEN_FILE",
19
+ "AWS_CREDENTIAL_PROFILES_FILE",
10
20
  "AWS_CONTAINER_CREDENTIALS_FULL_URI",
11
21
  "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI",
12
22
  "AWS_CONTAINER_AUTHORIZATION_TOKEN",
13
23
  "AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE",
24
+ "AWS_EC2_METADATA_SERVICE_ENDPOINT",
25
+ "AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE",
14
26
  "AWS_IGNORE_CONFIGURED_ENDPOINT_URLS",
27
+ "AWS_ENDPOINT_URL_PREFIX",
28
+ "AWS_ENDPOINT_URL_SUFFIX",
29
+ ];
30
+ const JAVA_OPTION_ENVIRONMENT_KEYS = [
31
+ "JAVA_TOOL_OPTIONS",
32
+ "JDK_JAVA_OPTIONS",
33
+ "_JAVA_OPTIONS",
34
+ "JAVA_OPTS",
35
+ "MAVEN_OPTS",
36
+ "GRADLE_OPTS",
37
+ "ANT_OPTS",
38
+ "SBT_OPTS",
39
+ ];
40
+ const JVM_WIDE_JAVA_OPTION_ENVIRONMENT_KEYS = [
41
+ "JAVA_TOOL_OPTIONS",
42
+ "JDK_JAVA_OPTIONS",
43
+ "_JAVA_OPTIONS",
15
44
  ];
45
+ export function normalizeEmulatorSdks(sdks = []) {
46
+ const unsupportedSdk = sdks.find((sdk) => !SUPPORTED_EMULATOR_SDKS.includes(sdk));
47
+ if (unsupportedSdk !== undefined) {
48
+ throw new Error(`Unsupported SDK: ${unsupportedSdk}. Choose from ${SUPPORTED_EMULATOR_SDKS.join(", ")}.`);
49
+ }
50
+ return [...new Set(sdks)];
51
+ }
52
+ export function resolveAwsRegion(region, defaultRegion = DEFAULT_AWS_REGION) {
53
+ const resolvedRegion = region ?? defaultRegion;
54
+ if (resolvedRegion.trim().length === 0)
55
+ throw new Error("Region must not be empty.");
56
+ return resolvedRegion;
57
+ }
16
58
  export function createEmulatorConnectionSettings(port, stateDirectory) {
17
59
  const endpointUrl = `https://127.0.0.1:${port}`;
18
60
  const portDirectory = path.join(stateDirectory, String(port));
@@ -22,9 +64,10 @@ export function createEmulatorConnectionSettings(port, stateDirectory) {
22
64
  AWS_CONFIG_FILE: path.join(portDirectory, "config"),
23
65
  AWS_CA_BUNDLE: path.join(portDirectory, "ca.pem"),
24
66
  AWS_EC2_METADATA_DISABLED: "true",
25
- AWS_REGION: "us-east-1",
26
- AWS_DEFAULT_REGION: "us-east-1",
67
+ AWS_REGION: DEFAULT_AWS_REGION,
68
+ AWS_DEFAULT_REGION: DEFAULT_AWS_REGION,
27
69
  NODE_EXTRA_CA_CERTS: path.join(portDirectory, "ca.pem"),
70
+ AWS_DISABLE_HOST_PREFIX_INJECTION: "true",
28
71
  };
29
72
  return {
30
73
  endpointUrl,
@@ -35,13 +78,96 @@ export function createEmulatorConnectionSettings(port, stateDirectory) {
35
78
  environment,
36
79
  };
37
80
  }
38
- export function createChildEnvironment(parentEnvironment, emulatorEnvironment) {
39
- const childEnvironment = { ...parentEnvironment, ...emulatorEnvironment };
40
- for (const key of AWS_CREDENTIAL_ENVIRONMENT_KEYS)
41
- delete childEnvironment[key];
81
+ export function createChildEnvironment(parentEnvironment, emulatorEnvironment, options = {}) {
82
+ const { sdks = [], region, platform = process.platform } = options;
83
+ const caseInsensitiveEnvironment = platform === "win32";
84
+ const normalizeName = (name) => caseInsensitiveEnvironment ? name.toUpperCase() : name;
85
+ const childEnvironment = { ...parentEnvironment };
86
+ const controlledEnvironmentKeys = new Set([
87
+ ...Object.keys(emulatorEnvironment),
88
+ ...AWS_CREDENTIAL_ENVIRONMENT_KEYS,
89
+ ...(sdks.includes("rust") || sdks.includes("dotnet") ? ["SSL_CERT_FILE"] : []),
90
+ ].map(normalizeName));
42
91
  for (const key of Object.keys(childEnvironment)) {
43
- if (key.startsWith("AWS_ENDPOINT_URL_"))
92
+ const normalizedKey = normalizeName(key);
93
+ if (controlledEnvironmentKeys.has(normalizedKey) || normalizedKey.startsWith("AWS_ENDPOINT_URL_")) {
44
94
  delete childEnvironment[key];
95
+ }
96
+ }
97
+ const childRegion = resolveAwsRegion(region, emulatorEnvironment.AWS_REGION);
98
+ Object.assign(childEnvironment, emulatorEnvironment, {
99
+ AWS_REGION: childRegion,
100
+ AWS_DEFAULT_REGION: childRegion,
101
+ });
102
+ if (sdks.includes("java-v2")) {
103
+ const inheritedJavaOptions = [];
104
+ const inheritedJvmWideOptions = [];
105
+ for (const name of JAVA_OPTION_ENVIRONMENT_KEYS) {
106
+ const matchingKeys = Object.keys(parentEnvironment)
107
+ .filter((key) => normalizeName(key) === normalizeName(name));
108
+ const values = matchingKeys
109
+ .map((key) => parentEnvironment[key])
110
+ .filter((value) => value !== undefined);
111
+ for (const key of Object.keys(childEnvironment)) {
112
+ if (normalizeName(key) === normalizeName(name))
113
+ delete childEnvironment[key];
114
+ }
115
+ if (values.length > 0) {
116
+ const combinedOptions = values.join(" ");
117
+ childEnvironment[name] = combinedOptions;
118
+ inheritedJavaOptions.push(combinedOptions);
119
+ if (JVM_WIDE_JAVA_OPTION_ENVIRONMENT_KEYS.includes(name)) {
120
+ inheritedJvmWideOptions.push(combinedOptions);
121
+ }
122
+ }
123
+ }
124
+ const existingOptions = childEnvironment.JAVA_TOOL_OPTIONS;
125
+ rejectJavaAwsOverrides(inheritedJavaOptions);
126
+ const hasConfiguredTrustStore = inheritedJvmWideOptions.some((options) => /(?:^|[\s"'])-Djavax\.net\.ssl\.trustStore(?:=|\s|["'])/.test(options));
127
+ const hasConfiguredTrustStoreType = inheritedJvmWideOptions.some((options) => /(?:^|[\s"'])-Djavax\.net\.ssl\.trustStoreType(?:=|\s|["'])/.test(options));
128
+ const hasIncompatibleTrustStoreTypeWithoutPath = inheritedJavaOptions.some((options) => {
129
+ const hasCustomTrustStore = /(?:^|[\s"'])-Djavax\.net\.ssl\.trustStore(?:=|\s|["'])/.test(options);
130
+ if (hasCustomTrustStore)
131
+ return false;
132
+ const types = [...options.matchAll(/(?:^|[\s"'])-Djavax\.net\.ssl\.trustStoreType=(?:"([^"]*)"|'([^']*)'|([^\s"']+))/g)]
133
+ .map((match) => match[1] ?? match[2] ?? match[3] ?? "");
134
+ return types.some((type) => type.toUpperCase() !== "PKCS12");
135
+ });
136
+ if (hasIncompatibleTrustStoreTypeWithoutPath) {
137
+ throw new Error("The emulator truststore uses PKCS12. Set javax.net.ssl.trustStoreType=PKCS12 or provide a compatible custom truststore with javax.net.ssl.trustStore.");
138
+ }
139
+ if (hasConfiguredTrustStore) {
140
+ childEnvironment.JAVA_TOOL_OPTIONS = existingOptions;
141
+ }
142
+ else {
143
+ const trustStore = path.join(path.dirname(emulatorEnvironment.AWS_CA_BUNDLE), "truststore.p12");
144
+ const trustStoreOption = quoteJavaToolOption(`-Djavax.net.ssl.trustStore=${trustStore}`);
145
+ childEnvironment.JAVA_TOOL_OPTIONS = [
146
+ existingOptions?.trim(),
147
+ trustStoreOption,
148
+ hasConfiguredTrustStoreType ? undefined : "-Djavax.net.ssl.trustStoreType=PKCS12",
149
+ ].filter(Boolean).join(" ");
150
+ }
151
+ }
152
+ if (sdks.includes("rust") || sdks.includes("dotnet")) {
153
+ childEnvironment.SSL_CERT_FILE = emulatorEnvironment.AWS_CA_BUNDLE;
45
154
  }
46
155
  return childEnvironment;
47
156
  }
157
+ function rejectJavaAwsOverrides(options) {
158
+ const property = /(?:^|[\s"'])-Daws\.(?:accessKeyId|secretAccessKey|secretKey|sessionToken|profile|webIdentityTokenFile|roleArn|roleSessionName|sharedCredentialsFile|configFile|ignoreConfiguredEndpointUrls|disableEc2Metadata|ec2MetadataServiceEndpointMode|ec2MetadataServiceEndpoint|endpointUrl(?:\.[A-Za-z0-9_-]+|[A-Z][A-Za-z0-9_-]*)?)(?==|\s|["'])/;
159
+ if (options.some((value) => /(?:^|[\s"'])@/.test(value))) {
160
+ throw new Error("Inherited JVM options reference an @argument file, which can hide AWS credential or endpoint overrides. Remove it when using --sdk java-v2.");
161
+ }
162
+ if (options.some((value) => property.test(value))) {
163
+ throw new Error("Inherited JVM options contain an AWS credential, profile, or endpoint override. Remove the aws.* system property so the emulator settings can be used.");
164
+ }
165
+ }
166
+ function quoteJavaToolOption(option) {
167
+ if (/[\r\n]/.test(option))
168
+ throw new Error("Java truststore path cannot contain line breaks.");
169
+ const quote = option.includes('"') ? "'" : '"';
170
+ if (option.includes(quote))
171
+ throw new Error("Java truststore path cannot contain both quote characters.");
172
+ return `${quote}${option}${quote}`;
173
+ }
@@ -1,3 +1,4 @@
1
+ import type { EmulatorSdk } from "./emulator-environment.js";
1
2
  export type StartEmulatorOptions = {
2
3
  version?: string;
3
4
  port?: number | string;
@@ -13,6 +14,10 @@ export type RunWithEmulatorOptions = StartEmulatorOptions & {
13
14
  * Defaults to false.
14
15
  */
15
16
  shell?: boolean;
17
+ /** Set AWS_REGION and AWS_DEFAULT_REGION for the child command. */
18
+ region?: string;
19
+ /** Add SDK-specific TLS settings for the selected SDK families. */
20
+ sdks?: EmulatorSdk[];
16
21
  };
17
22
  export type PrepareEmulatorOptions = Pick<StartEmulatorOptions, "version" | "signal">;
18
23
  export type ResolvedEmulatorOptions = {
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import { type EmulatorEnvironment } from "./emulator-environment.js";
2
2
  import { type PrepareEmulatorOptions, type RunWithEmulatorOptions, type StartEmulatorOptions } from "./emulator-options.js";
3
3
  export type { PrepareEmulatorOptions, RunWithEmulatorOptions, StartEmulatorOptions } from "./emulator-options.js";
4
- export type { EmulatorEnvironment } from "./emulator-environment.js";
4
+ export type { EmulatorEnvironment, EmulatorSdk } from "./emulator-environment.js";
5
5
  export type EmulatorSession = {
6
6
  version: string;
7
7
  port: number;
package/dist/index.js CHANGED
@@ -6,7 +6,7 @@ import os from "node:os";
6
6
  import path from "node:path";
7
7
  import { createRetryableStop, startContainer, stopContainer, withEmulator } from "./container-lifecycle.js";
8
8
  import { docker, throwIfAborted } from "./docker.js";
9
- import { createChildEnvironment, createEmulatorConnectionSettings } from "./emulator-environment.js";
9
+ import { createChildEnvironment, createEmulatorConnectionSettings, normalizeEmulatorSdks, resolveAwsRegion, } from "./emulator-environment.js";
10
10
  import { ensureEmulatorImage, getArchitecture } from "./emulator-image.js";
11
11
  import { resolveEmulatorOptions, resolveEmulatorVersion, } from "./emulator-options.js";
12
12
  import { runCommand } from "./process.js";
@@ -157,9 +157,11 @@ export async function startEmulator(options = {}) {
157
157
  export async function runWithEmulator(command, args = [], options = {}) {
158
158
  if (!command)
159
159
  throw new Error("A command is required.");
160
- const { shell = false, ...emulatorOptions } = options;
160
+ const { shell = false, sdks: requestedSdks = [], region, ...emulatorOptions } = options;
161
+ const childRegion = resolveAwsRegion(region);
162
+ const sdks = normalizeEmulatorSdks(requestedSdks);
161
163
  return withEmulator(() => startEmulator(emulatorOptions), async (emulator) => {
162
- const childEnvironment = createChildEnvironment(process.env, emulator.environment);
164
+ const childEnvironment = createChildEnvironment(process.env, emulator.environment, { sdks, region: childRegion });
163
165
  return runCommand(command, args, childEnvironment, emulatorOptions.signal, shell);
164
166
  });
165
167
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "awesome-emulator-cli",
3
- "version": "0.3.0",
4
- "description": "Awesome Emulator CLI for use with AWS Emulator in local tests from npm scripts or Node.js. It runs the upstream Linux package in Docker.",
3
+ "version": "0.4.0",
4
+ "description": "Run tests for AWS SDKs in any language; the CLI manages the local emulator in Docker.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
7
7
  "types": "./dist/index.d.ts",