[doc]: add javadoc for sdk/sdk-testing package (#200)

* add javadoc for sdk/sdk-testing package

* fix some javadoc

* add some more javadoc

* add some more javadoc

Author: zhongkechen

examples/src/main/java/software/amazon/lambda/durable/examples/GenericInputOutputExample.java

@@ -16,8 +16,8 @@
 /**
  * Example demonstrating a durable Lambda function that uses generic types in input and output.
  *
- * <p>This example shows how to use TypeToken to work with generic types like List<String>, Map<String, List<String,
- * String>, and nested generics that cannot be represented by simple Class objects.
+ * <p>This example shows how to use TypeToken to work with generic types like {@code List<String>}, {@code Map<String,
+ * List<String>>}, and nested generics that cannot be represented by simple Class objects.
  */
 public class GenericInputOutputExample
         extends DurableHandler<Map<String, String>, Map<String, Map<String, List<String>>>> {

examples/src/main/java/software/amazon/lambda/durable/examples/GenericTypesExample.java

@@ -16,8 +16,8 @@
 /**
  * Example demonstrating TypeToken support for complex generic types.
  *
- * <p>This example shows how to use TypeToken to work with generic types like List<String>, Map<String, Object>, and
- * nested generics that cannot be represented by simple Class objects.
+ * <p>This example shows how to use TypeToken to work with generic types like {@code List<String>}, {@code Map<String,
+ * Object>}, and nested generics that cannot be represented by simple Class objects.
  */
 public class GenericTypesExample extends DurableHandler<GenericTypesExample.Input, GenericTypesExample.Output> {
 

pom.xml

@@ -9,7 +9,7 @@
     <version>0.7.0-SNAPSHOT</version>
     <packaging>pom</packaging>
 
-    <name>AWS Lambda Durable Execution SDK Parent</name>
+    <name>AWS Lambda Durable Execution SDK</name>
     <description>Parent POM for AWS Lambda Durable Execution SDK and Examples</description>
     <url>https://github.com/aws/aws-durable-execution-sdk-java</url>
 

sdk-testing/src/main/java/software/amazon/lambda/durable/testing/CloudDurableTestRunner.java

@@ -11,6 +11,13 @@
 import software.amazon.lambda.durable.TypeToken;
 import software.amazon.lambda.durable.serde.JacksonSerDes;
 
+/**
+ * Test runner for durable Lambda functions deployed to AWS. Invokes a real Lambda function, polls execution history,
+ * and returns structured test results.
+ *
+ * @param <I> the handler input type
+ * @param <O> the handler output type
+ */
 public class CloudDurableTestRunner<I, O> {
     private final String functionArn;
     private final TypeToken<I> inputType;
@@ -39,11 +46,13 @@ private CloudDurableTestRunner(
         this.invocationType = invocationType;
     }
 
+    /** Creates a runner for the given function ARN with Class-based input/output types. */
     public static <I, O> CloudDurableTestRunner<I, O> create(
             String functionArn, Class<I> inputType, Class<O> outputType) {
         return create(functionArn, TypeToken.get(inputType), TypeToken.get(outputType));
     }
 
+    /** Creates a runner for the given function ARN with TypeToken-based input/output types. */
     public static <I, O> CloudDurableTestRunner<I, O> create(
             String functionArn, TypeToken<I> inputType, TypeToken<O> outputType) {
         return new CloudDurableTestRunner<>(
@@ -59,11 +68,13 @@ public static <I, O> CloudDurableTestRunner<I, O> create(
                 InvocationType.REQUEST_RESPONSE);
     }
 
+    /** Creates a runner with a custom {@link LambdaClient} and Class-based input/output types. */
     public static <I, O> CloudDurableTestRunner<I, O> create(
             String functionArn, Class<I> inputType, Class<O> outputType, LambdaClient lambdaClient) {
         return create(functionArn, TypeToken.get(inputType), TypeToken.get(outputType), lambdaClient);
     }
 
+    /** Creates a runner with a custom {@link LambdaClient} and TypeToken-based input/output types. */
     public static <I, O> CloudDurableTestRunner<I, O> create(
             String functionArn, TypeToken<I> inputType, TypeToken<O> outputType, LambdaClient lambdaClient) {
         return new CloudDurableTestRunner<>(
@@ -76,21 +87,25 @@ public static <I, O> CloudDurableTestRunner<I, O> create(
                 InvocationType.REQUEST_RESPONSE);
     }
 
+    /** Returns a new runner with the specified poll interval between history checks. */
     public CloudDurableTestRunner<I, O> withPollInterval(Duration interval) {
         return new CloudDurableTestRunner<>(
                 functionArn, inputType, outputType, lambdaClient, interval, timeout, invocationType);
     }
 
+    /** Returns a new runner with the specified maximum wait time for execution completion. */
     public CloudDurableTestRunner<I, O> withTimeout(Duration timeout) {
         return new CloudDurableTestRunner<>(
                 functionArn, inputType, outputType, lambdaClient, pollInterval, timeout, invocationType);
     }
 
+    /** Returns a new runner with the specified Lambda invocation type. */
     public CloudDurableTestRunner<I, O> withInvocationType(InvocationType type) {
         return new CloudDurableTestRunner<>(
                 functionArn, inputType, outputType, lambdaClient, pollInterval, timeout, type);
     }
 
+    /** Invokes the Lambda function, polls execution history until completion, and returns the result. */
     public TestResult<O> run(I input) {
         try {
             // Serialize input
@@ -167,6 +182,7 @@ public AsyncExecution<O> startAsync(I input) {
         }
     }
 
+    /** Returns the {@link TestOperation} for the given name from the last execution result. */
     public TestOperation getOperation(String name) {
         if (lastResult == null) {
             throw new IllegalStateException("No execution has been run yet");

sdk-testing/src/main/java/software/amazon/lambda/durable/testing/HistoryEventProcessor.java

@@ -19,9 +19,21 @@
 import software.amazon.lambda.durable.model.ExecutionStatus;
 import software.amazon.lambda.durable.serde.JacksonSerDes;
 
+/**
+ * Processes execution history events from the GetDurableExecutionHistory API into {@link TestResult} objects. Used by
+ * {@link CloudDurableTestRunner} and {@link AsyncExecution} to convert cloud execution history into testable results.
+ */
 public class HistoryEventProcessor {
     private final JacksonSerDes serDes = new JacksonSerDes();
 
+    /**
+     * Processes a list of execution history events into a structured {@link TestResult}.
+     *
+     * @param events the raw history events from the GetDurableExecutionHistory API
+     * @param outputType the expected output type for deserialization
+     * @param <O> the handler output type
+     * @return a TestResult containing the execution status, output, and operation details
+     */
     public <O> TestResult<O> processEvents(List<Event> events, TypeToken<O> outputType) {
         var operations = new HashMap<String, Operation>();
         var operationEvents = new HashMap<String, List<Event>>();

sdk-testing/src/main/java/software/amazon/lambda/durable/testing/HistoryPoller.java

@@ -11,13 +11,27 @@
 import software.amazon.awssdk.services.lambda.model.EventType;
 import software.amazon.awssdk.services.lambda.model.GetDurableExecutionHistoryRequest;
 
+/**
+ * Polls the GetDurableExecutionHistory API until execution completes or a timeout is reached. Used by
+ * {@link CloudDurableTestRunner} for synchronous test execution.
+ */
 public class HistoryPoller {
     private final LambdaClient lambdaClient;
 
+    /** Creates a poller backed by the given Lambda client. */
     public HistoryPoller(LambdaClient lambdaClient) {
         this.lambdaClient = lambdaClient;
     }
 
+    /**
+     * Polls execution history until a terminal event is found or the timeout is exceeded.
+     *
+     * @param executionArn the durable execution ARN to poll
+     * @param pollInterval the interval between poll requests
+     * @param timeout the maximum time to wait for completion
+     * @return all history events collected during polling
+     * @throws RuntimeException if the timeout is exceeded or polling is interrupted
+     */
     public List<Event> pollUntilComplete(String executionArn, Duration pollInterval, Duration timeout) {
         var allEvents = new ArrayList<Event>();
         var startTime = Instant.now();

sdk-testing/src/main/java/software/amazon/lambda/durable/testing/LocalDurableTestRunner.java

@@ -22,6 +22,13 @@
 import software.amazon.lambda.durable.serde.JacksonSerDes;
 import software.amazon.lambda.durable.serde.SerDes;
 
+/**
+ * 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.
+ *
+ * @param <I> the handler input type
+ * @param <O> the handler output type
+ */
 public class LocalDurableTestRunner<I, O> {
     private static final int MAX_INVOCATIONS = 100;
 
@@ -51,6 +58,12 @@ private LocalDurableTestRunner(
     /**
      * Creates a LocalDurableTestRunner with default configuration. Use this method when your handler uses the default
      * DurableConfig.
+     *
+     * @param inputType The input type class
+     * @param handlerFn The handler function
+     * @param <I> Input type
+     * @param <O> Output type
+     * @return LocalDurableTestRunner with default configuration
      */
     public static <I, O> LocalDurableTestRunner<I, O> create(
             Class<I> inputType, BiFunction<I, DurableContext, O> handlerFn) {
@@ -81,6 +94,13 @@ public static <I, O> LocalDurableTestRunner<I, O> create(
     /**
      * 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.
+     *
+     * @param inputType The input type class
+     * @param handlerFn The handler function
+     * @param config The DurableConfig to use (DurableExecutionClient will be overridden with in-memory implementation)
+     * @param <I> Input type
+     * @param <O> Output type
+     * @return LocalDurableTestRunner configured with the provided settings
      */
     public static <I, O> LocalDurableTestRunner<I, O> create(
             Class<I> inputType, BiFunction<I, DurableContext, O> handlerFn, DurableConfig config) {
@@ -129,6 +149,12 @@ public static <I, O> LocalDurableTestRunner<I, O> create(
      * 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.
+     *
+     * @param inputType The input type class
+     * @param handler The DurableHandler instance to test
+     * @param <I> Input type
+     * @param <O> Output type
+     * @return LocalDurableTestRunner configured with the handler's settings
      */
     public static <I, O> LocalDurableTestRunner<I, O> create(Class<I> inputType, DurableHandler<I, O> handler) {
         return new LocalDurableTestRunner<>(
@@ -220,14 +246,17 @@ public TestResult<O> runUntilComplete(I input) {
         return result;
     }
 
+    /** Resets a named step operation to STARTED status, simulating a checkpoint failure. */
     public void resetCheckpointToStarted(String stepName) {
         storage.resetCheckpointToStarted(stepName);
     }
 
+    /** Removes a named step operation entirely, simulating loss of a fire-and-forget checkpoint. */
     public void simulateFireAndForgetCheckpointLoss(String stepName) {
         storage.simulateFireAndForgetCheckpointLoss(stepName);
     }
 
+    /** Returns the {@link TestOperation} for the given operation name, or null if not found. */
     public TestOperation getOperation(String name) {
         var op = storage.getOperationByName(name);
         return op != null ? new TestOperation(op, serDes) : null;
@@ -253,27 +282,27 @@ public void timeoutCallback(String callbackId) {
         storage.timeoutCallback(callbackId);
     }
 
-    // Manual time advancement for skipTime=false scenarios
+    /** Advances all pending operations, simulating time passing for retries and waits. */
     public void advanceTime() {
         storage.advanceReadyOperations();
     }
 
-    // Manual complete a chained invoke call
+    /** Completes a chained invoke operation with a successful result. */
     public void completeChainedInvoke(String name, String result) {
         storage.completeChainedInvoke(name, new OperationResult(OperationStatus.SUCCEEDED, result, null));
     }
 
-    // Manual mark a chained invoke call TIMEOUT
+    /** Marks a chained invoke operation as timed out. */
     public void timeoutChainedInvoke(String name) {
         storage.completeChainedInvoke(name, new OperationResult(OperationStatus.TIMED_OUT, null, null));
     }
 
-    // Manual fail a chained invoke call
+    /** Fails a chained invoke operation with the given error. */
     public void failChainedInvoke(String name, ErrorObject error) {
         storage.completeChainedInvoke(name, new OperationResult(OperationStatus.FAILED, null, error));
     }
 
-    // Manual stop a chained invoke call
+    /** Stops a chained invoke operation with the given error. */
     public void stopChainedInvoke(String name, ErrorObject error) {
         storage.completeChainedInvoke(name, new OperationResult(OperationStatus.STOPPED, null, error));
     }

sdk-testing/src/main/java/software/amazon/lambda/durable/testing/LocalMemoryExecutionClient.java

@@ -17,6 +17,10 @@
 import software.amazon.lambda.durable.serde.JacksonSerDes;
 import software.amazon.lambda.durable.serde.SerDes;
 
+/**
+ * In-memory implementation of {@link DurableExecutionClient} for local testing. Stores operations and checkpoint state
+ * in memory, simulating the durable execution backend without AWS infrastructure.
+ */
 public class LocalMemoryExecutionClient implements DurableExecutionClient {
     private final Map<String, Operation> operations = new ConcurrentHashMap<>();
     private final List<Event> allEvents = new CopyOnWriteArrayList<>();
@@ -96,6 +100,7 @@ public boolean advanceReadyOperations() {
         return replaced.get();
     }
 
+    /** Completes a chained invoke operation with the given result, simulating a child Lambda response. */
     public void completeChainedInvoke(String name, OperationResult result) {
         var op = getOperationByName(name);
         if (op == null) {
@@ -126,17 +131,20 @@ public void completeChainedInvoke(String name, OperationResult result) {
         }
     }
 
+    /** Returns the operation with the given name, or null if not found. */
     public Operation getOperationByName(String name) {
         return operations.values().stream()
                 .filter(op -> name.equals(op.name()))
                 .findFirst()
                 .orElse(null);
     }
 
+    /** Returns all operations currently stored. */
     public List<Operation> getAllOperations() {
         return operations.values().stream().toList();
     }
 
+    /** Clears all operations and events, resetting the client to its initial state. */
     public void reset() {
         operations.clear();
         allEvents.clear();

sdk-testing/src/main/java/software/amazon/lambda/durable/testing/TestOperation.java

@@ -30,39 +30,47 @@ public class TestOperation {
         this.serDes = serDes;
     }
 
+    /** Returns the raw history events associated with this operation. */
     public List<Event> getEvents() {
         return List.copyOf(events);
     }
 
+    /** Returns the operation name. */
     public String getName() {
         return operation.name();
     }
 
+    /** Returns the current status of this operation (e.g. STARTED, SUCCEEDED, FAILED). */
     public OperationStatus getStatus() {
         return operation.status();
     }
 
+    /** Returns the operation type (STEP, WAIT, CALLBACK, etc.). */
     public OperationType getType() {
         return operation.type();
     }
 
+    /** Returns the step details, or null if this is not a step operation. */
     public StepDetails getStepDetails() {
         return operation.stepDetails();
     }
 
+    /** Returns the wait details, or null if this is not a wait operation. */
     public WaitDetails getWaitDetails() {
         return operation.waitDetails();
     }
 
+    /** Returns the callback details, or null if this is not a callback operation. */
     public CallbackDetails getCallbackDetails() {
         return operation.callbackDetails();
     }
 
+    /** Deserializes and returns the step result as the given type. */
     public <T> T getStepResult(Class<T> type) {
         return getStepResult(TypeToken.get(type));
     }
 
-    /** Type-safe result extraction from step details. */
+    /** Deserializes and returns the step result using a TypeToken for generic types. */
     public <T> T getStepResult(TypeToken<T> type) {
         var details = operation.stepDetails();
         if (details == null || details.result() == null) {
@@ -71,11 +79,13 @@ public <T> T getStepResult(TypeToken<T> type) {
         return serDes.deserialize(details.result(), type);
     }
 
+    /** Returns the step error, or null if the step succeeded or this is not a step operation. */
     public ErrorObject getError() {
         var details = operation.stepDetails();
         return details != null ? details.error() : null;
     }
 
+    /** Returns the current retry attempt number (1-based), defaulting to 1 if not available. */
     public int getAttempt() {
         var details = operation.stepDetails();
         return details != null && details.attempt() != null ? details.attempt() : 1;