docs: testing section

Replace the testing documentation with a language-neutral section
covering the local runner, authoring a test, inspecting operations,
the full API surface, workflow patterns, cloud runner, and SAM CLI.
Every section now has TypeScript, Python, and Java tabs with real,
verified examples from the actual testing SDK sources.

Structure
- Add runner.md, authoring.md, assertions.md, api-reference.md,
  workflow-patterns.md, cloud-runner.md, sam-cli.md.
- Drop basic-tests.md, complex-workflows.md, stores.md,
  testing-modes.md, write-tests.md, test-operations.md,
  test-workflows.md, testing-tools.md, run-in-cloud.md, and the
  corresponding examples directories.
- Reorder the nav to Runner, Authoring, Assertions, API Reference,
  Workflow Patterns, Cloud Runner, SAM CLI.

Highlights
- Document DURABLE_EXECUTION_TIME_SCALE for the Python testing SDK
  under Authoring / Skip time in tests, with cross-links from the
  Long waits workflow pattern and the API reference Control time
  section.
- API reference reorganised by intent verbs (Create a runner, Run
  the handler, Drive callbacks, etc.) with explicit anchors on
  duplicated Cloud-side headings so in-page links resolve.
- Cloud runner page regrouped so Deploy, Configure polling, and
  IAM permissions live under Set up the cloud runner, and each
  troubleshooting tip has its own heading.
- Use the correct JS testing package name
  (@aws/durable-execution-sdk-js-testing).
- Verified every method, argument, type, and return value against
  the TS, Python, and Java SDK and testing SDK sources.
- Verified the SAM CLI commands against sam --help locally.

Closes #24
Closes #25
Closes #44
Closes #45
Closes #46
Closes #47
Closes #50
Closes #62
Closes #63
Closes #64
Closes #68
Closes #80
Closes #81
Closes #82
Closes #86
Closes #133

Author: yaythomas

docs/testing/api-reference.md

@@ -0,0 +1,160 @@
+# Assertions
+
+After `run()` completes, the test result contains the full operation history. You can
+look up operations by name, filter by type, or walk the history to assert on what ran
+and how it ran.
+
+## Assert on a step
+
+Look up a step by name and check its status and result.
+
+=== "TypeScript"
+
+    Use `runner.getOperation(name)` to get a handle to the operation, then call
+    `getStepDetails()` to access the result.
+
+    ```typescript
+    --8<-- "examples/typescript/testing/assertions/assert-step.ts"
+    ```
+
+=== "Python"
+
+    Use `result.get_step(name)` to get the `StepOperation`. The `result` attribute holds the
+    raw serialized payload.
+
+    ```python
+    --8<-- "examples/python/testing/assertions/assert-step.py"
+    ```
+
+=== "Java"
+
+    Use `result.getOperation(name)` to get the `TestOperation`, then call
+    `getStepResult(Class<T>)` to deserialize the result.
+
+    ```java
+    --8<-- "examples/java/testing/assertions/assert-step.java"
+    ```
+
+## Assert on a wait
+
+Look up a wait operation and check that it was scheduled with the expected duration.
+
+=== "TypeScript"
+
+    `getWaitDetails()` returns `waitSeconds` and `scheduledEndTimestamp`.
+
+    ```typescript
+    --8<-- "examples/typescript/testing/assertions/assert-wait.ts"
+    ```
+
+=== "Python"
+
+    Use `result.get_wait(name)`. The `scheduled_end_timestamp` attribute is a `datetime`
+    when the wait was scheduled to end.
+
+    ```python
+    --8<-- "examples/python/testing/assertions/assert-wait.py"
+    ```
+
+=== "Java"
+
+    `getWaitDetails().scheduledEndTimestamp()` returns the scheduled end time as an
+    `Instant`.
+
+    ```java
+    --8<-- "examples/java/testing/assertions/assert-wait.java"
+    ```
+
+## Assert on a callback
+
+For callbacks, the test drives the execution to the point where the callback is waiting,
+then completes it from the test.
+
+=== "TypeScript"
+
+    Use `waitForData(WaitingOperationStatus.SUBMITTED)` to wait until the callback submitter
+    has run, then call `sendCallbackSuccess()` to complete it.
+
+    ```typescript
+    --8<-- "examples/typescript/testing/assertions/assert-callback.ts"
+    ```
+
+=== "Python"
+
+    Use `run_async()` to start the execution, `wait_for_callback()` to get the callback ID,
+    `send_callback_success()` to complete it, then `wait_for_result()` to get the final
+    result. All calls must happen inside the `with runner:` block.
+
+    ```python
+    --8<-- "examples/python/testing/assertions/assert-callback.py"
+    ```
+
+=== "Java"
+
+    Use `run()` to reach the PENDING state, `getCallbackId()` to get the callback ID,
+    `completeCallback()` to complete it, then `run()` again to finish the execution.
+
+    ```java
+    --8<-- "examples/java/testing/assertions/assert-callback.java"
+    ```
+
+## Assert on a child context
+
+Child contexts appear as `CONTEXT` operations in the result. You can walk their child
+operations to assert on what ran inside the context.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/testing/assertions/assert-child-context.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/testing/assertions/assert-child-context.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/testing/assertions/assert-child-context.java"
+    ```
+
+## Filter operations by status
+
+When a step retries, the operation history contains one entry per attempt. Filter by
+status to count failures and successes separately.
+
+=== "TypeScript"
+
+    Pass `{ status: OperationStatus.FAILED }` to `result.getOperations()` to filter.
+
+    ```typescript
+    --8<-- "examples/typescript/testing/assertions/filter-by-status.ts"
+    ```
+
+=== "Python"
+
+    Use `result.get_all_operations()` to get a flat list including nested operations, then
+    filter by `op.status`.
+
+    ```python
+    --8<-- "examples/python/testing/assertions/filter-by-status.py"
+    ```
+
+=== "Java"
+
+    `result.getFailedOperations()` and `result.getSucceededOperations()` return pre-filtered
+    lists.
+
+    ```java
+    --8<-- "examples/java/testing/assertions/filter-by-status.java"
+    ```
+
+## See also
+
+- [Authoring](authoring.md) Set up the test runner and write your first test.
+- [Cloud Runner](cloud-runner.md) Run tests against a deployed Lambda function.
+- [Step](../sdk-reference/operations/step.md)
+- [Wait](../sdk-reference/operations/wait.md)

docs/testing/assertions.md

@@ -0,0 +1,180 @@
+# Authoring
+
+## Install the testing SDK
+
+=== "TypeScript"
+
+    ```bash
+    npm install --save-dev @aws/durable-execution-sdk-js-testing
+    ```
+
+=== "Python"
+
+    ```bash
+    pip install aws-durable-execution-sdk-python-testing
+    ```
+
+=== "Java"
+
+    Add the testing dependency to your build file with `test` scope:
+
+    ```xml
+    <dependency>
+      <groupId>software.amazon.lambda</groupId>
+      <artifactId>aws-durable-execution-sdk-java-testing</artifactId>
+      <scope>test</scope>
+    </dependency>
+    ```
+
+## Write a minimal test
+
+Create a runner with your handler, call `run()`, and assert on the result.
+
+=== "TypeScript"
+
+    Call `setupTestEnvironment()` in `beforeAll` and `teardownTestEnvironment()` in
+    `afterAll`. Create a new runner instance in `beforeEach` so each test starts with a
+    clean state.
+
+    ```typescript
+    --8<-- "examples/typescript/testing/authoring/minimal-test.ts"
+    ```
+
+=== "Python"
+
+    Use `DurableFunctionTestRunner` as a context manager. The context manager starts the
+    scheduler thread on entry and stops it on exit.
+
+    ```python
+    --8<-- "examples/python/testing/authoring/minimal-test.py"
+    ```
+
+=== "Java"
+
+    Use `LocalDurableTestRunner.create()` with the input type and a handler function. Call
+    `runUntilComplete()` to drive the full replay loop until the execution completes or
+    fails.
+
+    ```java
+    --8<-- "examples/java/testing/authoring/minimal-test.java"
+    ```
+
+## Test a failed execution
+
+When your handler throws outside a step, or a step exhausts all retries, the execution
+fails. Assert on the status and inspect the error.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/testing/authoring/test-failure.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/testing/authoring/test-failure.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/testing/authoring/test-failure.java"
+    ```
+
+## Test retries
+
+The test runner drives the full retry loop via replay. Configure a retry strategy on the
+step, and the runner re-invokes the handler as many times as needed.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/testing/authoring/test-retries.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/testing/authoring/test-retries.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/testing/authoring/test-retries.java"
+    ```
+
+## Skip time in tests
+
+Retry backoffs and `context.wait()` durations use real time in production. The test
+runner collapses these delays so tests finish in milliseconds.
+
+=== "TypeScript"
+
+    Pass `{ skipTime: true }` to `setupTestEnvironment()`. The runner swaps its real timer
+    for a queue that fires immediately. Both `context.wait()` delays and step retry delays
+    complete in zero wall-clock time.
+
+    ```typescript
+    await LocalDurableTestRunner.setupTestEnvironment({ skipTime: true });
+    ```
+
+=== "Python"
+
+    Set the `DURABLE_EXECUTION_TIME_SCALE` environment variable to a float that multiplies
+    `context.wait()` durations. Set it to `0` for instant waits, or to a small fraction such
+    as `0.01` to run waits at 100x speed. Step retry delays use the configured
+    `next_attempt_delay_seconds` at real wall-clock time, and the scale does not apply to
+    them. Keep retry delays short in tests, or configure a retry strategy with a low
+    `initial_delay_seconds`.
+
+    ```bash
+    DURABLE_EXECUTION_TIME_SCALE=0 pytest tests/my_wait_tests.py
+    ```
+
+=== "Java"
+
+    `runUntilComplete()` calls `advanceTime()` after each invocation. `advanceTime()`
+    immediately marks PENDING step retries as READY and completes STARTED waits without
+    real-time sleeps. If you call `run()` directly, call `advanceTime()` yourself between
+    invocations.
+
+    ```java
+    runner.runUntilComplete(input); // advanceTime() runs after each invocation
+    ```
+
+See [Workflow patterns: Long waits](workflow-patterns.md#long-waits) for a worked
+example.
+
+## Test branching logic
+
+Run the same handler with different inputs to cover each branch. Each test case gets its
+own runner instance.
+
+=== "TypeScript"
+
+    ```typescript
+    --8<-- "examples/typescript/testing/authoring/test-branching.ts"
+    ```
+
+=== "Python"
+
+    ```python
+    --8<-- "examples/python/testing/authoring/test-branching.py"
+    ```
+
+=== "Java"
+
+    ```java
+    --8<-- "examples/java/testing/authoring/test-branching.java"
+    ```
+
+## See also
+
+- [API Reference](api-reference.md) Full reference for the runner, result, and operation
+    classes.
+- [Workflow patterns](workflow-patterns.md) Complete tests for common workflow shapes.
+- [Assertions](assertions.md) Inspect steps, waits, and callbacks after a test run.
+- [Cloud Runner](cloud-runner.md) Run the same tests against a deployed Lambda function.
+- [SAM CLI](sam-cli.md) Local and remote invocation with SAM CLI.