Package software.amazon.lambda.durable.testing

Class LocalDurableTestRunner<I,O>

java.lang.Object
software.amazon.lambda.durable.testing.LocalDurableTestRunner<I,O>
Type Parameters:
I - the handler input type
O - the handler output type
public class LocalDurableTestRunner<I,O> extends Object
In-memory test runner for durable Lambda functions. Simulates the Lambda re-invocation loop locally without requiring AWS infrastructure, enabling fast unit and integration tests.

  • Method Details

    • create

      public static <I, O> LocalDurableTestRunner<I,O> create(Class<I> inputType, BiFunction<I,DurableContext,O> handlerFn)
      Creates a LocalDurableTestRunner with default configuration. Use this method when your handler uses the default DurableConfig.
      Type Parameters:
      I - Input type
      O - Output type
      Parameters:
      inputType - The input type class
      handlerFn - The handler function
      Returns:
      LocalDurableTestRunner with default configuration

    • create

      public static <I, O> LocalDurableTestRunner<I,O> create(TypeToken<I> inputType, BiFunction<I,DurableContext,O> handlerFn)
      Creates a LocalDurableTestRunner with default configuration. Use this method when your handler uses the default DurableConfig.

      If your handler has custom configuration (custom SerDes, ExecutorService, etc.), use create(TypeToken, DurableHandler) instead to ensure the test runner uses the same configuration as your handler.

      Optionally, you can also use create(TypeToken, BiFunction, DurableConfig) to pass in any DurableConfig directly.

      Type Parameters:
      I - Input type
      O - Output type
      Parameters:
      inputType - The input type class
      handlerFn - The handler function
      Returns:
      LocalDurableTestRunner with default configuration

    • create

      public static <I, O> LocalDurableTestRunner<I,O> create(Class<I> inputType, BiFunction<I,DurableContext,O> handlerFn, DurableConfig config)
      Creates a LocalDurableTestRunner that uses a custom configuration. This allows the test runner to use custom SerDes and other configuration, while overriding the DurableExecutionClient with the in-memory implementation.
      Type Parameters:
      I - Input type
      O - Output type
      Parameters:
      inputType - The input type class
      handlerFn - The handler function
      config - The DurableConfig to use (DurableExecutionClient will be overridden with in-memory implementation)
      Returns:
      LocalDurableTestRunner configured with the provided settings

    • create

      public static <I, O> LocalDurableTestRunner<I,O> create(TypeToken<I> inputType, BiFunction<I,DurableContext,O> handlerFn, DurableConfig config)
      Creates a LocalDurableTestRunner that uses a custom configuration. This allows the test runner to use custom SerDes and other configuration, while overriding the DurableExecutionClient with the in-memory implementation.

      Use this method when you need to pass a custom DurableConfig directly, for example when testing with a custom SerDes without using a DurableHandler.

      Example usage: 

      
 // Create a custom DurableConfig with custom SerDes
 var config = DurableConfig.builder()
     .withSerDes(new MyCustomSerDes())
     .build();

 // Create test runner with custom configuration
 var runner = LocalDurableTestRunner.create(
     String.class,
     (input, context) -> context.step("process", String.class, stepCtx -> "result"),
     config
 );

 // Run test with custom configuration
 var result = runner.run("test-input");
 assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
      Type Parameters:
      I - Input type
      O - Output type
      Parameters:
      inputType - The input type class
      handlerFn - The handler function
      config - The DurableConfig to use (DurableExecutionClient will be overridden with in-memory implementation)
      Returns:
      LocalDurableTestRunner configured with the provided settings

    • create

      public static <I, O> LocalDurableTestRunner<I,O> create(Class<I> inputType, DurableHandler<I,O> handler)
      Creates a LocalDurableTestRunner from a DurableHandler instance, automatically extracting the configuration. This is a convenient method when you have a handler instance and want to test it with the same configuration it uses in production.
      Type Parameters:
      I - Input type
      O - Output type
      Parameters:
      inputType - The input type class
      handler - The DurableHandler instance to test
      Returns:
      LocalDurableTestRunner configured with the handler's settings

    • create

      public static <I, O> LocalDurableTestRunner<I,O> create(TypeToken<I> inputType, DurableHandler<I,O> handler)
      Creates a LocalDurableTestRunner from a DurableHandler instance, automatically extracting the configuration. This is a convenient method when you have a handler instance and want to test it with the same configuration it uses in production.

      This method automatically:

      • Uses the handler's configuration (SerDes, ExecutorService, etc.)
      • Overrides the DurableExecutionClient with the in-memory implementation for testing

      Example usage: 

      
 // Create handler instance
 var handler = new MyCustomHandler();

 // Create test runner from handler (automatically extracts config)
 var runner = LocalDurableTestRunner.create(String.class, handler);

 // Run test with the handler's configuration
 var result = runner.run("test-input");
 assertEquals(ExecutionStatus.SUCCEEDED, result.getStatus());
      Type Parameters:
      I - Input type
      O - Output type
      Parameters:
      inputType - The input type class
      handler - The DurableHandler instance to test
      Returns:
      LocalDurableTestRunner configured with the handler's settings

    • run

      public TestResult<O> run(I input)
      Run a single invocation (may return PENDING if waiting/retrying).

    • runUntilComplete

      public TestResult<O> runUntilComplete(I input)
      Run until completion (SUCCEEDED or FAILED) or pending manual intervention, simulating Lambda re-invocations. Operations that don't require manual intervention (like WAIT in STARTED or STEP in PENDING) will be automatically advanced.
      Parameters:
      input - The input to process
      Returns:
      Final test result (SUCCEEDED or FAILED) or PENDING if operations pending manual intervention

    • resetCheckpointToStarted

      public void resetCheckpointToStarted(String stepName)
      Resets a named step operation to STARTED status, simulating a checkpoint failure.

    • simulateFireAndForgetCheckpointLoss

      public void simulateFireAndForgetCheckpointLoss(String stepName)
      Removes a named step operation entirely, simulating loss of a fire-and-forget checkpoint.

    • getOperation

      public TestOperation getOperation(String name)
      Returns the TestOperation for the given operation name, or null if not found.

    • getCallbackId

      public String getCallbackId(String operationName)
      Get callback ID for a named callback operation.

    • completeCallback

      public void completeCallback(String callbackId, String result)
      Complete a callback with success result.

    • failCallback

      public void failCallback(String callbackId, software.amazon.awssdk.services.lambda.model.ErrorObject error)
      Fail a callback with error.

    • timeoutCallback

      public void timeoutCallback(String callbackId)
      Timeout a callback.

    • advanceTime

      public void advanceTime()
      Advances all pending operations, simulating time passing for retries and waits.

    • completeChainedInvoke

      public void completeChainedInvoke(String name, String result)
      Completes a chained invoke operation with a successful result.

    • timeoutChainedInvoke

      public void timeoutChainedInvoke(String name)
      Marks a chained invoke operation as timed out.

    • failChainedInvoke

      public void failChainedInvoke(String name, software.amazon.awssdk.services.lambda.model.ErrorObject error)
      Fails a chained invoke operation with the given error.

    • stopChainedInvoke

      public void stopChainedInvoke(String name, software.amazon.awssdk.services.lambda.model.ErrorObject error)
      Stops a chained invoke operation with the given error.