awesome-emulator-cli 0.1.2 → 0.3.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 +12 -0
- package/dist/cli.js +15 -5
- package/dist/emulator-options.d.ts +3 -0
- package/dist/emulator-options.js +6 -3
- package/dist/index.d.ts +4 -2
- package/dist/index.js +7 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# Awesome Emulator CLI
|
|
2
2
|
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="./assets/social-preview.png" alt="Awesome Emulator CLI — Local emulator testing for Node.js" width="100%">
|
|
5
|
+
</p>
|
|
6
|
+
|
|
3
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.
|
|
4
8
|
|
|
5
9
|
This is an independent project and is not affiliated with or endorsed by Amazon Web Services.
|
|
@@ -12,6 +16,14 @@ This is an independent project and is not affiliated with or endorsed by Amazon
|
|
|
12
16
|
|
|
13
17
|
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.
|
|
14
18
|
|
|
19
|
+
Prepare the image ahead of the first test run with:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
npx awesome-emulator prepare
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
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.
|
|
26
|
+
|
|
15
27
|
## Run a test command
|
|
16
28
|
|
|
17
29
|
```sh
|
package/dist/cli.js
CHANGED
|
@@ -1,16 +1,18 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { runWithEmulator, startEmulator } from "./index.js";
|
|
2
|
+
import { prepareEmulatorImage, runWithEmulator, startEmulator } from "./index.js";
|
|
3
|
+
import { DEFAULT_VERSION } from "./emulator-options.js";
|
|
3
4
|
import { FORWARDED_SIGNALS, getSignalExitCode } from "./signals.js";
|
|
4
5
|
function usage() {
|
|
5
6
|
console.log(`Usage:
|
|
7
|
+
awesome-emulator prepare [--version <version>]
|
|
6
8
|
awesome-emulator start [options]
|
|
7
9
|
awesome-emulator run [options] [--shell] -- <command> [args...]
|
|
8
10
|
|
|
9
11
|
Options:
|
|
10
|
-
-v, --version <version> AWS Emulator version (default:
|
|
11
|
-
-p, --port <port> Host port; 0 chooses an available port (default: 9297)
|
|
12
|
-
-t, --telemetry <on|off> Telemetry setting (default: on)
|
|
13
|
-
--memory <limit> Container memory limit (default: 2g)
|
|
12
|
+
-v, --version <version> AWS Emulator version (default: ${DEFAULT_VERSION})
|
|
13
|
+
-p, --port <port> (start/run) Host port; 0 chooses an available port (default: 9297)
|
|
14
|
+
-t, --telemetry <on|off> (start/run) Telemetry setting (default: on)
|
|
15
|
+
--memory <limit> (start/run) Container memory limit (default: 2g)
|
|
14
16
|
--shell (run only) Enable .cmd/.bat and built-ins; trusted values only
|
|
15
17
|
-h, --help Show this help`);
|
|
16
18
|
}
|
|
@@ -48,6 +50,9 @@ function parse(argv) {
|
|
|
48
50
|
const key = optionNames[token];
|
|
49
51
|
if (!key)
|
|
50
52
|
throw new Error(`Unknown option: ${token}`);
|
|
53
|
+
if (command === "prepare" && key !== "version") {
|
|
54
|
+
throw new Error(`${token} can only be used with the start or run command.`);
|
|
55
|
+
}
|
|
51
56
|
const value = argv[index + 1];
|
|
52
57
|
if (!value || value.startsWith("--"))
|
|
53
58
|
throw new Error(`Missing value for ${token}`);
|
|
@@ -83,6 +88,11 @@ async function main(signal) {
|
|
|
83
88
|
throw new Error("Usage: awesome-emulator run [options] -- <command> [args...]");
|
|
84
89
|
return runWithEmulator(program, args, { ...parsed.options, signal });
|
|
85
90
|
}
|
|
91
|
+
if (parsed.command === "prepare") {
|
|
92
|
+
const image = await prepareEmulatorImage({ version: parsed.options.version, signal });
|
|
93
|
+
console.log(`AWS Emulator image is ready: ${image}`);
|
|
94
|
+
return 0;
|
|
95
|
+
}
|
|
86
96
|
if (parsed.command === "start") {
|
|
87
97
|
const emulator = await startEmulator({
|
|
88
98
|
version: parsed.options.version,
|
|
@@ -14,6 +14,7 @@ export type RunWithEmulatorOptions = StartEmulatorOptions & {
|
|
|
14
14
|
*/
|
|
15
15
|
shell?: boolean;
|
|
16
16
|
};
|
|
17
|
+
export type PrepareEmulatorOptions = Pick<StartEmulatorOptions, "version" | "signal">;
|
|
17
18
|
export type ResolvedEmulatorOptions = {
|
|
18
19
|
version: string;
|
|
19
20
|
requestedPort: number;
|
|
@@ -21,4 +22,6 @@ export type ResolvedEmulatorOptions = {
|
|
|
21
22
|
memory: string;
|
|
22
23
|
startupTimeoutMs: number;
|
|
23
24
|
};
|
|
25
|
+
export declare const DEFAULT_VERSION = "1.0.533";
|
|
26
|
+
export declare function resolveEmulatorVersion(value: string | undefined, environment?: NodeJS.ProcessEnv): string;
|
|
24
27
|
export declare function resolveEmulatorOptions(options: StartEmulatorOptions, environment?: NodeJS.ProcessEnv): ResolvedEmulatorOptions;
|
package/dist/emulator-options.js
CHANGED
|
@@ -1,13 +1,16 @@
|
|
|
1
|
-
const DEFAULT_VERSION = "1.0.
|
|
1
|
+
export const DEFAULT_VERSION = "1.0.533";
|
|
2
2
|
const DEFAULT_PORT = 9297;
|
|
3
3
|
const DEFAULT_MEMORY = "2g";
|
|
4
4
|
function normalizeVersion(value, environment) {
|
|
5
5
|
const version = value ?? environment.AWS_EMULATOR_VERSION ?? DEFAULT_VERSION;
|
|
6
6
|
if (!/^\d+\.\d+\.\d+$/.test(String(version))) {
|
|
7
|
-
throw new Error(`Invalid AWS Emulator version: ${version}. Use a version such as
|
|
7
|
+
throw new Error(`Invalid AWS Emulator version: ${version}. Use a version such as ${DEFAULT_VERSION}.`);
|
|
8
8
|
}
|
|
9
9
|
return String(version);
|
|
10
10
|
}
|
|
11
|
+
export function resolveEmulatorVersion(value, environment = process.env) {
|
|
12
|
+
return normalizeVersion(value, environment);
|
|
13
|
+
}
|
|
11
14
|
function normalizePort(value, environment) {
|
|
12
15
|
const port = Number(value ?? environment.AWS_EMULATOR_PORT ?? DEFAULT_PORT);
|
|
13
16
|
if (!Number.isInteger(port) || port < 0 || port > 65535) {
|
|
@@ -39,7 +42,7 @@ function normalizeStartupTimeout(value) {
|
|
|
39
42
|
}
|
|
40
43
|
export function resolveEmulatorOptions(options, environment = process.env) {
|
|
41
44
|
return {
|
|
42
|
-
version:
|
|
45
|
+
version: resolveEmulatorVersion(options.version, environment),
|
|
43
46
|
requestedPort: normalizePort(options.port, environment),
|
|
44
47
|
telemetry: normalizeTelemetry(options.telemetry, environment),
|
|
45
48
|
memory: normalizeMemory(options.memory),
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type EmulatorEnvironment } from "./emulator-environment.js";
|
|
2
|
-
import { type RunWithEmulatorOptions, type StartEmulatorOptions } from "./emulator-options.js";
|
|
3
|
-
export type { RunWithEmulatorOptions, StartEmulatorOptions } from "./emulator-options.js";
|
|
2
|
+
import { type PrepareEmulatorOptions, type RunWithEmulatorOptions, type StartEmulatorOptions } from "./emulator-options.js";
|
|
3
|
+
export type { PrepareEmulatorOptions, RunWithEmulatorOptions, StartEmulatorOptions } from "./emulator-options.js";
|
|
4
4
|
export type { EmulatorEnvironment } from "./emulator-environment.js";
|
|
5
5
|
export type EmulatorSession = {
|
|
6
6
|
version: string;
|
|
@@ -14,6 +14,8 @@ export type EmulatorSession = {
|
|
|
14
14
|
containerId: string;
|
|
15
15
|
stop: () => Promise<void>;
|
|
16
16
|
};
|
|
17
|
+
/** Build or reuse the selected AWS Emulator Docker image without starting a container. */
|
|
18
|
+
export declare function prepareEmulatorImage(options?: PrepareEmulatorOptions): Promise<string>;
|
|
17
19
|
/**
|
|
18
20
|
* Start AWS Emulator in a local Docker container.
|
|
19
21
|
*
|
package/dist/index.js
CHANGED
|
@@ -8,8 +8,14 @@ import { createRetryableStop, startContainer, stopContainer, withEmulator } from
|
|
|
8
8
|
import { docker, throwIfAborted } from "./docker.js";
|
|
9
9
|
import { createChildEnvironment, createEmulatorConnectionSettings } from "./emulator-environment.js";
|
|
10
10
|
import { ensureEmulatorImage, getArchitecture } from "./emulator-image.js";
|
|
11
|
-
import { resolveEmulatorOptions } from "./emulator-options.js";
|
|
11
|
+
import { resolveEmulatorOptions, resolveEmulatorVersion, } from "./emulator-options.js";
|
|
12
12
|
import { runCommand } from "./process.js";
|
|
13
|
+
/** Build or reuse the selected AWS Emulator Docker image without starting a container. */
|
|
14
|
+
export async function prepareEmulatorImage(options = {}) {
|
|
15
|
+
throwIfAborted(options.signal);
|
|
16
|
+
const version = resolveEmulatorVersion(options.version);
|
|
17
|
+
return ensureEmulatorImage(version, getArchitecture(), options.signal);
|
|
18
|
+
}
|
|
13
19
|
async function getAvailablePort() {
|
|
14
20
|
const server = net.createServer();
|
|
15
21
|
await new Promise((resolve, reject) => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "awesome-emulator-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
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.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
"prebuild": "node scripts/clean-dist.js",
|
|
19
19
|
"build": "tsc -p tsconfig.json",
|
|
20
20
|
"test": "npm run build && node --test",
|
|
21
|
+
"test:unit": "node --test",
|
|
21
22
|
"test:integration": "node --test test/integration.test.js",
|
|
22
23
|
"prepare": "npm run build",
|
|
23
24
|
"prepack": "npm run build",
|