fix(testing-sdk): skip in-process timers and use queue for scheduler when skipTime is enabled (#298)

*Issue #, if available:*

#262

*Description of changes:*

skipTime had issues where it would cause invalid checkpoints since it
was creating invocations too early. For example, if the language SDK
created 3 retry operations, the invocation would stay open until
setTimeout resolved in waitBeforeContinue:
https://github.com/aws/aws-durable-execution-sdk-js/blob/959f20601a4056aed868075d7c9868632a55bb3b/packages/aws-durable-execution-sdk-js/src/utils/wait-before-continue/wait-before-continue.ts#L69-L83

But with skipTime enabled, it would just schedule all the invocation
retries immediately and cause concurrent invocations with invalid
checkpoint data.

To fix this, I am adding fake timers to the testing library with
`@sinonjs/fake-timers`, and adding queue scheduling instead of timer
scheduling when skip time is enabled.

Fake timers:
- `@sinonjs/fake-timers` is the same fake timers library that `sinon`
and `jest` use.
- It allows advancing the timers from `setTimeout` and other timers that
may be running in the user's handler.
- To support this, the customer now has to configure skipTime globally
on `LocalDurableTestRunner.setupTestEnvironment`. This will configure
the entire nodejs process to use fake timers, so it should be a global
property. `LocalDurableTestRunner.teardownTestEnvironment` will clean up
the fake timers.

Queue scheduling:
- Instead of scheduling invocations with timers with 0ms delay, they are
now all queued for execution
- No invocations can occur in parallel anymore, but if they do, it will
be queued up to run as soon as possible instead of scheduled for later
execution. This may not match the behaviour without skipTime, but it's
better than causing potential non-determinism with 0ms timers.

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

@@ -1,37 +1,25 @@
-import { LocalDurableTestRunner } from "@aws/durable-execution-sdk-js-testing";
 import { handler } from "./promise-all";
+import { createTests } from "../../../utils/test-helper";
 
-beforeAll(() => LocalDurableTestRunner.setupTestEnvironment());
-afterAll(() => LocalDurableTestRunner.teardownTestEnvironment());
+createTests({
+  name: "promise-all test",
+  functionName: "promise-all",
+  handler,
+  tests: (runner) => {
+    it("should complete all promises", async () => {
+      const execution = await runner.run();
 
-describe("promise-all test", () => {
-  const durableTestRunner = new LocalDurableTestRunner({
-    handlerFunction: handler,
-    skipTime: true,
-  });
+      expect(execution.getOperations()).toHaveLength(4);
+    });
 
-  it("should complete all promises", async () => {
-    const execution = await durableTestRunner.run();
+    it("should return correct result - happy case", async () => {
+      const execution = await runner.run();
 
-    expect(execution.getOperations()).toHaveLength(4);
-  });
-
-  it("should return correct result - happy case", async () => {
-    const execution = await durableTestRunner.run();
-
-    expect(execution.getResult()).toStrictEqual([
-      "result 1",
-      "result 2",
-      "result 3",
-    ]);
-  });
-
-  // TODO: enable following test once SDK/testing lib is fixed to handle concurrent retries
-  // it("should fail if a promise fails - failure case", async () => {
-  //     durableTestRunner.getOperationByIndex(0).mockRejectedValue(new Error("ERROR"));
-  //
-  //     const execution = await durableTestRunner.run();
-  //
-  //     expect(execution.getError()).toBeDefined();
-  // });
+      expect(execution.getResult()).toStrictEqual([
+        "result 1",
+        "result 2",
+        "result 3",
+      ]);
+    });
+  },
 });

packages/aws-durable-execution-sdk-js-examples/src/examples/promise/all/promise-all.test.ts

@@ -4,11 +4,8 @@ import { createTests } from "../../../utils/test-helper";
 createTests<string>({
   name: "promise-any test",
   functionName: "promise-any",
-  localRunnerConfig: {
-    skipTime: false,
-  },
   handler,
-  tests: (runner, isCloud) => {
+  tests: (runner) => {
     it("should return first successful promise result", async () => {
       const execution = await runner.run();
 

packages/aws-durable-execution-sdk-js-examples/src/examples/promise/any/promise-any.test.ts

@@ -14,13 +14,14 @@ jest.mock("@aws-sdk/client-dynamodb", () => ({
   GetItemCommand: jest.fn().mockImplementation((params) => params),
 }));
 
-beforeAll(() => LocalDurableTestRunner.setupTestEnvironment());
+beforeAll(() =>
+  LocalDurableTestRunner.setupTestEnvironment({ skipTime: true }),
+);
 afterAll(() => LocalDurableTestRunner.teardownTestEnvironment());
 
 describe("steps-with-retry", () => {
   const durableTestRunner = new LocalDurableTestRunner({
     handlerFunction: handler,
-    skipTime: true,
   });
 
   jest.spyOn(Math, "random").mockReturnValue(0.5);

packages/aws-durable-execution-sdk-js-examples/src/examples/step/steps-with-retry/steps-with-retry.test.ts

@@ -7,13 +7,14 @@ import { handler } from "./step-with-retry";
 
 const EXPECTED_RESULT = "step succeeded";
 
-beforeAll(() => LocalDurableTestRunner.setupTestEnvironment());
+beforeAll(() =>
+  LocalDurableTestRunner.setupTestEnvironment({ skipTime: true }),
+);
 afterAll(() => LocalDurableTestRunner.teardownTestEnvironment());
 
 describe("step-with-retry test", () => {
   const durableTestRunner = new LocalDurableTestRunner({
     handlerFunction: handler,
-    skipTime: true,
   });
 
   it("should return expected result - happy case", async () => {

packages/aws-durable-execution-sdk-js-examples/src/examples/step/with-retry/step-with-retry.test.ts

@@ -63,13 +63,16 @@ export function createTests<ResultType>(testDef: TestDefinition<ResultType>) {
   }
 
   describe(`${testDef.name} (local)`, () => {
-    beforeAll(() => LocalDurableTestRunner.setupTestEnvironment());
+    beforeAll(() =>
+      LocalDurableTestRunner.setupTestEnvironment({
+        skipTime: testDef.localRunnerConfig?.skipTime ?? true,
+      }),
+    );
     afterAll(() => LocalDurableTestRunner.teardownTestEnvironment());
 
     const runner: LocalDurableTestRunner<ResultType> =
       new LocalDurableTestRunner({
         handlerFunction: testDef.handler,
-        skipTime: testDef.localRunnerConfig?.skipTime ?? true,
       });
 
     beforeEach(() => {

packages/aws-durable-execution-sdk-js-examples/src/utils/test-helper.ts

@@ -41,6 +41,7 @@
     "@types/aws-lambda": "^8.10.150",
     "@types/express": "^5.0.2",
     "@types/morgan": "^1.9.10",
+    "@types/sinonjs__fake-timers": "^15.0.1",
     "@types/supertest": "^6.0.3",
     "eslint": "^9.29.0",
     "eslint-config-prettier": "^10.1.5",
@@ -54,6 +55,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-lambda": "*",
+    "@sinonjs/fake-timers": "^13.0.5",
     "@smithy/smithy-client": "^4.9.1",
     "express": "^5.1.0"
   },

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

@@ -50,11 +50,12 @@ async function runDurable() {
     const handler = (module.handler ??
       module.default) as LambdaHandler<DurableExecutionInvocationInput>;
 
-    await LocalDurableTestRunner.setupTestEnvironment();
+    await LocalDurableTestRunner.setupTestEnvironment({
+      skipTime,
+    });
 
     const runner = new LocalDurableTestRunner({
       handlerFunction: handler,
-      skipTime,
     });
 
     console.log(`Running durable function from: ${filePath}`);

packages/aws-durable-execution-sdk-js-testing/src/cli/run-durable.ts

@@ -5,29 +5,31 @@ import {
 } from "@aws/durable-execution-sdk-js";
 import { OperationStatus } from "@aws-sdk/client-lambda";
 
-beforeAll(() => LocalDurableTestRunner.setupTestEnvironment());
+beforeAll(() =>
+  LocalDurableTestRunner.setupTestEnvironment({ skipTime: true }),
+);
 afterAll(() => LocalDurableTestRunner.teardownTestEnvironment());
 
 describe("LocalDurableTestRunner Integration", () => {
   const originalEnv = process.env;
 
   afterEach(() => {
     process.env = originalEnv;
+    jest.useRealTimers();
   });
 
   it("should complete execution with no environment variables set", async () => {
     process.env = {};
 
     const handler = withDurableExecution(
-      async (event: unknown, context: DurableContext) => {
+      async (_event: unknown, context: DurableContext) => {
         const result = await context.step(() => Promise.resolve("completed"));
         return { success: true, step: result };
       },
     );
 
     const runner = new LocalDurableTestRunner({
       handlerFunction: handler,
-      skipTime: true,
     });
 
     const result = await runner.run();
@@ -64,7 +66,6 @@ describe("LocalDurableTestRunner Integration", () => {
 
     const runner = new LocalDurableTestRunner({
       handlerFunction: handler,
-      skipTime: true,
     });
 
     // Get operations for verification
@@ -254,6 +255,52 @@ describe("LocalDurableTestRunner Integration", () => {
     ]);
   });
 
+  it("should complete with mocking", async () => {
+    const mockedFunction = jest.fn();
+
+    const otherCode = {
+      property: () => "not mocked",
+    };
+
+    const handler = withDurableExecution(
+      async (_event: unknown, context: DurableContext) => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+        const mock1: string = await context.step(() => mockedFunction());
+
+        return mock1 + " and " + otherCode.property();
+      },
+    );
+
+    jest.spyOn(otherCode, "property").mockReturnValue("my result");
+
+    const runner = new LocalDurableTestRunner({
+      handlerFunction: handler,
+    });
+
+    mockedFunction.mockResolvedValue("hello world");
+
+    const result = await runner.run();
+
+    expect(result.getResult()).toEqual("hello world and my result");
+  });
+
+  it("should have fake timers in the global scope", async () => {
+    jest.useRealTimers();
+
+    const handler = withDurableExecution(() => {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+      return Promise.resolve((Date as unknown as any).isFake);
+    });
+
+    const runner = new LocalDurableTestRunner({
+      handlerFunction: handler,
+    });
+
+    const result = await runner.run();
+
+    expect(result.getResult()).toBe(true);
+  });
+
   // enable when language SDK supports concurrent waits
   it.skip("should prevent scheduled function interference in parallel wait scenario", async () => {
     // This test creates a scenario where multiple wait operations could create

packages/aws-durable-execution-sdk-js-testing/src/test-runner/local/__tests__/integration/local-durable-test-runner.integration.test.ts

@@ -6,7 +6,11 @@ import {
 } from "@aws/durable-execution-sdk-js";
 import { OperationStatus } from "@aws-sdk/client-lambda";
 
-beforeAll(() => LocalDurableTestRunner.setupTestEnvironment());
+beforeAll(() =>
+  LocalDurableTestRunner.setupTestEnvironment({
+    skipTime: true,
+  }),
+);
 afterAll(() => LocalDurableTestRunner.teardownTestEnvironment());
 
 /**
@@ -71,7 +75,6 @@ describe("WaitForCallback Operations Integration", () => {
 
       const runner = new LocalDurableTestRunner({
         handlerFunction: handler,
-        skipTime: true,
       });
 
       // Get all callback operations by index
@@ -172,7 +175,6 @@ describe("WaitForCallback Operations Integration", () => {
 
         const runner = new LocalDurableTestRunner({
           handlerFunction: handler,
-          skipTime: true,
         });
 
         const result = await runner.run({
@@ -216,7 +218,6 @@ describe("WaitForCallback Operations Integration", () => {
 
         const runner = new LocalDurableTestRunner({
           handlerFunction: handler,
-          skipTime: true,
         });
 
         const result = await runner.run({
@@ -286,7 +287,6 @@ describe("WaitForCallback Operations Integration", () => {
 
       const runner = new LocalDurableTestRunner({
         handlerFunction: handler,
-        skipTime: true,
       });
 
       const result = await runner.run({