feat(testing-sdk): add full support for run-durable CLI (#392)

*Issue #, if available:*

#388

*Description of changes:*

run-durable CLI is currently not exported from our package, but it is
advertised.

It also uses unintuitive arguments which would not be easy to maintain.
Since it's not working right now, we can improve this before actually
launching it.

Changes:
- Change language SDK DurableExecutionInvocationInputWithClient to work
for objects that look the same, even if they are not the same instance.
This is necessary since customers might bundle the language SDK when
running their script, and we need the testing library to work with
different instances as long as they match.
- Using `commander` library as a dependency for the testing library for
argument parsing
- Change default skipTime to false for more accurate testing by default
- Refactor run-durable CLI to separate files
- Add unit and integration tests for run-durable CLI with CJS and MJS
handlers

Example usage:
```
npx run-durable --show-history step-basic.js
```

or with a custom loader

```
NODE_OPTIONS="--import tsx" npx run-durable --show-history step-basic.ts
```


By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.

Author: anthonyting

package-lock.json

@@ -14,7 +14,7 @@
     "postpublish": "git restore .",
     "clean": "rm -rf node_modules && npm run clean --workspaces --if-present",
     "prepare": "husky install",
-    "run-durable": "ORIGINAL_CWD=$PWD npm run run-durable -w packages/aws-durable-execution-sdk-js-testing --"
+    "run-durable": "NODE_OPTIONS=\"--import tsx\" npx run-durable --"
   },
   "repository": {
     "type": "git",

package.json

@@ -65,7 +65,7 @@
     "@types/node": "^22.13.5",
     "argparse": "^2.0.1",
     "eslint": "^9.23.0",
-    "jest": "^29.7.0",
+    "jest": "^30.2.0",
     "js-yaml": "^4.1.0",
     "prettier": "^3.5.2",
     "ts-jest": "^29.2.6",

packages/aws-durable-execution-sdk-js-examples/package.json

@@ -0,0 +1,67 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`run-durable CLI Integration Tests with format=cjs Core Error Cases should error when file does not exist 1`] = `
+"Error: File not found: nonexistent-file.js
+"
+`;
+
+exports[`run-durable CLI Integration Tests with format=cjs End-to-End Execution should successfully execute test handler end-to-end 1`] = `
+[
+  "Skip time: false, Verbose: false, Show history: false",
+  "",
+  "No operations found.",
+  "",
+  "Execution Status: SUCCEEDED",
+  "",
+  "Result:",
+  ""Test CLI Success!"",
+  "",
+]
+`;
+
+exports[`run-durable CLI Integration Tests with format=cjs End-to-End Execution should successfully execute with custom handler export 1`] = `
+[
+  "Skip time: false, Verbose: false, Show history: false",
+  "",
+  "No operations found.",
+  "",
+  "Execution Status: SUCCEEDED",
+  "",
+  "Result:",
+  ""Custom Handler Success!"",
+  "",
+]
+`;
+
+exports[`run-durable CLI Integration Tests with format=mjs Core Error Cases should error when file does not exist 1`] = `
+"Error: File not found: nonexistent-file.js
+"
+`;
+
+exports[`run-durable CLI Integration Tests with format=mjs End-to-End Execution should successfully execute test handler end-to-end 1`] = `
+[
+  "Skip time: false, Verbose: false, Show history: false",
+  "",
+  "No operations found.",
+  "",
+  "Execution Status: SUCCEEDED",
+  "",
+  "Result:",
+  ""Test CLI Success!"",
+  "",
+]
+`;
+
+exports[`run-durable CLI Integration Tests with format=mjs End-to-End Execution should successfully execute with custom handler export 1`] = `
+[
+  "Skip time: false, Verbose: false, Show history: false",
+  "",
+  "No operations found.",
+  "",
+  "Execution Status: SUCCEEDED",
+  "",
+  "Result:",
+  ""Custom Handler Success!"",
+  "",
+]
+`;

packages/aws-durable-execution-sdk-js-examples/src/__tests__/__snapshots__/run-durable.integration.test.ts.snap

@@ -0,0 +1,9 @@
+const { withDurableExecution } = require("@aws/durable-execution-sdk-js");
+
+module.exports.handler = withDurableExecution(async (event, context) => {
+  return "Test CLI Success!";
+});
+
+module.exports.customHandler = withDurableExecution(async (event, context) => {
+  return "Custom Handler Success!";
+});

packages/aws-durable-execution-sdk-js-examples/src/__tests__/fixtures/test-handler.cjs

@@ -0,0 +1,12 @@
+// Test handler for CLI integration tests
+// This file is committed and doesn't require a build step
+
+import { withDurableExecution } from "@aws/durable-execution-sdk-js";
+
+export const handler = withDurableExecution(async (event, context) => {
+  return "Test CLI Success!";
+});
+
+export const customHandler = withDurableExecution(async (event, context) => {
+  return "Custom Handler Success!";
+});

packages/aws-durable-execution-sdk-js-examples/src/__tests__/fixtures/test-handler.mjs

@@ -0,0 +1,88 @@
+import { execSync } from "child_process";
+import { join } from "path";
+
+const TEST_HANDLER_PATH = join(__dirname, "fixtures/test-handler");
+
+/**
+ * Helper function to execute CLI commands and capture output
+ */
+function runDurableCli(args: string[]): {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+} {
+  try {
+    const stdout = execSync(`npx run-durable ${args.join(" ")}`, {
+      encoding: "utf8",
+      cwd: join(__dirname, "../../../aws-durable-execution-sdk-js-testing"),
+      timeout: 30000,
+    });
+    return { stdout, stderr: "", exitCode: 0 };
+  } catch (error: any) {
+    return {
+      stdout: error.stdout || "",
+      stderr: error.stderr || "",
+      exitCode: error.status || 1,
+    };
+  }
+}
+
+describe.each(["cjs", "mjs"])(
+  `run-durable CLI Integration Tests with format=%s`,
+  (format) => {
+    const testHandlerPath = `${TEST_HANDLER_PATH}.${format}`;
+
+    describe("End-to-End Execution", () => {
+      it("should successfully execute test handler end-to-end", () => {
+        const { stdout, stderr, exitCode } = runDurableCli([testHandlerPath]);
+
+        expect(stderr).toBe("");
+
+        const lines = stdout.split("\n");
+        expect(lines[0]).toContain("Running durable function from");
+        expect(lines.slice(1)).toMatchSnapshot();
+        expect(exitCode).toBe(0);
+      });
+
+      it("should successfully execute with custom handler export", () => {
+        const { stdout, stderr, exitCode } = runDurableCli([
+          testHandlerPath,
+          "--handler-export",
+          "customHandler",
+        ]);
+
+        expect(stderr).toBe("");
+        const lines = stdout.split("\n");
+        expect(lines[0]).toContain("Running durable function from");
+        expect(lines.slice(1)).toMatchSnapshot();
+        expect(exitCode).toBe(0);
+      });
+    });
+
+    describe("Core Error Cases", () => {
+      it("should error when file does not exist", () => {
+        const { stdout, stderr, exitCode } = runDurableCli([
+          "nonexistent-file.js",
+        ]);
+
+        expect(exitCode).toBe(1);
+        expect(stdout).toBe("");
+        expect(stderr).toMatchSnapshot();
+      });
+
+      it("should error when handler export not found", () => {
+        const { stdout, stderr, exitCode } = runDurableCli([
+          testHandlerPath,
+          "--handler-export",
+          "nonExistentHandler",
+        ]);
+
+        expect(exitCode).toBe(1);
+        expect(stdout).toBe("");
+        expect(stderr).toContain(
+          "Error: Export 'nonExistentHandler' not found in ",
+        );
+      });
+    });
+  },
+);

packages/aws-durable-execution-sdk-js-examples/src/__tests__/run-durable.integration.test.ts

@@ -22,6 +22,11 @@ This package provides testing tools for durable functions both locally and in th
   - **Callback testing** - Send callback responses and verify callback behavior
   - **Retry validation** - Test step retry logic and failure scenarios
 
+- **run-durable CLI** - Command-line tool for quick testing without writing test code
+  - **Zero setup** - Run any durable function with `npx run-durable your-function.js`
+  - **Operation inspection** - View detailed operation tables and execution history
+  - **Time control** - Skip time for fast testing or use real timing for validation
+
 ## Installation
 
 ```bash
@@ -159,6 +164,7 @@ describe("CloudDurableTestRunner", () => {
 This README provides a quick reference for the Testing SDK's main features. For more detailed information:
 
 - **[API Reference](../../docs/api-reference/durable-execution-sdk-js-testing.md)** - Complete technical reference with detailed type definitions and operation specifications
+- **[run-durable CLI Guide](./RUN_DURABLE_CLI.md)** - Complete guide for using the command-line tool to quickly test durable functions
 - **[Contributing](../../CONTRIBUTING.md)** - Learn about contributing to the AWS Durable Execution Testing SDK for JavaScript
 
 ## LocalDurableTestRunner

packages/aws-durable-execution-sdk-js-testing/README.md

@@ -5,54 +5,68 @@ A command-line tool to quickly run and test durable functions locally without wr
 ## Usage
 
 ```bash
-npm run run-durable -- <path-to-handler-file> [no-skip-time] [verbose] [show-history]
+npx run-durable [options] <file>
 ```
 
-### Parameters
+### Arguments
 
-1. **Path to handler file** (required) - Path to the TypeScript file containing the durable function
-2. **no-skip-time** (optional) - Disables time skipping; waits will actually wait for the specified duration
-   - Default: time skipping is enabled (waits complete instantly)
-3. **verbose** (optional) - Enables verbose logging to see detailed execution flow
-   - Default: verbose logging is disabled
-4. **show-history** (optional) - Displays a table of history events after execution
-   - Default: history is not shown
+- **`<file>`** (required) - Path to the TypeScript or JavaScript file containing the durable function
+
+### Options
+
+- **`--skip-time`** - Enable time skipping in test environment; waits complete instantly
+  - Default: time skipping is disabled (waits actually wait for the specified duration)
+- **`-v, --verbose`** - Enable verbose logging output
+  - Default: verbose logging is disabled
+- **`--show-history`** - Display execution history events after completion
+  - Default: history is not shown
+- **`--handler-export <name>`** - The exported handler function key
+  - Default: "handler"
+- **`--help`** - Show help information
+- **`--version`** - Show version number
 
 ## Examples
 
 ### Basic Usage
 
 ```bash
-# Run with default settings (skip time, no verbose, no history)
-npm run run-durable -- packages/aws-durable-execution-sdk-js-examples/src/examples/hello-world.ts
+# Run with default settings (no skip time, no verbose, no history)
+npx run-durable hello-world.js
 ```
 
-### With Time Skipping Disabled
+### With Time Skipping Enabled
 
 ```bash
-# Actually wait for the specified duration
-npm run run-durable -- packages/aws-durable-execution-sdk-js-examples/src/examples/test-wait-simple.ts no-skip-time
+# Skip time - waits complete instantly
+npx run-durable test-wait-simple.js
 ```
 
 ### With Verbose Logging
 
 ```bash
 # See detailed execution logs
-npm run run-durable -- packages/aws-durable-execution-sdk-js-examples/src/examples/step-basic.ts skip-time verbose
+npx run-durable -v step-basic.js
 ```
 
 ### With History Display
 
 ```bash
 # Show history events table
-npm run run-durable -- packages/aws-durable-execution-sdk-js-examples/src/examples/step-basic.ts skip-time no-verbose show-history
+npx run-durable --show-history step-basic.js
+```
+
+### Custom Handler Export
+
+```bash
+# Use a custom export name instead of "handler"
+npx run-durable --handler-export my-function.js
 ```
 
 ### All Options Combined
 
 ```bash
-# Don't skip time + verbose logging + show history
-npm run run-durable -- packages/aws-durable-execution-sdk-js-examples/src/examples/comprehensive-operations.ts no-skip-time verbose show-history
+# Skip time + verbose logging + show history
+npx run-durable --skip-time --verbose --show-history comprehensive-operations.js
 ```
 
 ## Output
@@ -82,7 +96,7 @@ When `show-history` is enabled, you'll see a detailed table including:
 - **EventType**: ExecutionStarted, StepStarted, StepSucceeded, WaitStarted, WaitSucceeded, etc.
 - **EventId**: Sequential event identifier
 - **Id**: Operation identifier
-- **EventTimestamp**: Unix timestamp of the event
+- **EventTimestamp**: Timestamp of the event
 - **Event-specific details**: StartedDetails, SucceededDetails, FailedDetails, etc.
 
 ## Requirements
@@ -95,7 +109,7 @@ When `show-history` is enabled, you'll see a detailed table including:
 ```
 Checkpoint server listening on port 54867
 Running durable function from: packages/aws-durable-execution-sdk-js-examples/src/examples/step-basic.ts
-Skip time: true, Verbose: false, Show history: false
+Skip time: false, Verbose: false, Show history: false
 
 ┌─────────┬──────────┬──────┬────────┬─────────┬─────────────┬────────────────────────────┬────────────────────────────┬──────────┐
 │ (index) │ parentId │ name │ type   │ subType │ status      │ startTime                  │ endTime                    │ duration │
@@ -111,37 +125,39 @@ Result:
 
 ## Running from Different Locations
 
-### From monorepo root:
+The CLI accepts both absolute and relative file paths, making it easy to run from any directory:
 
-```bash
-npm run run-durable -- packages/aws-durable-execution-sdk-js-examples/src/examples/hello-world.ts
-```
-
-### From testing package directory:
+### From any directory with relative paths:
 
 ```bash
-npm run run-durable -- ../aws-durable-execution-sdk-js-examples/src/examples/hello-world.ts
+npx run-durable ./src/examples/hello-world.js
 ```
 
-### From examples package directory:
+### With absolute paths:
 
 ```bash
-npm run run-durable -- src/examples/hello-world.ts
+npx run-durable /full/path/to/your/durable-function.js
 ```
 
 ## Troubleshooting
 
 **Function hangs or doesn't complete:**
 
-- Try running with `verbose` to see detailed execution logs
+- Try running with `--verbose` to see detailed execution logs
 - Check if there are any infinite loops or blocking operations
 
+**Time-based operations take too long:**
+
+- Use `--skip-time` to make waits complete instantly for faster testing
+- Default behavior is to actually wait for the specified duration
+
 **Time-based operations complete instantly:**
 
-- This is expected behavior with default settings
-- Use `no-skip-time` parameter to actually wait for the specified duration
+- This happens when using `--skip-time` flag
+- Remove the `--skip-time` flag if you want waits to actually wait for the specified duration
 
 **Cannot find handler:**
 
 - Ensure the file exports `handler` or `default`
+- Use `--handler-export <name>` if your handler has a different export name
 - Verify the path is correct relative to where you're running the command