Testing API Reference¶

new LocalDurableTestRunner({ handlerFunction: handler })

Call LocalDurableTestRunner.setupTestEnvironment() in beforeAll and LocalDurableTestRunner.teardownTestEnvironment() in afterAll.

static setupTestEnvironment(params?: LocalDurableTestRunnerSetupParameters): Promise<void>
static teardownTestEnvironment(): Promise<void>

Constructor parameters:

• handlerFunction (required) The handler created with withDurableExecution.

DurableFunctionTestRunner(handler=handler, poll_interval=1.0)

Use as a context manager. The context manager starts the scheduler thread on entry and stops it on exit.

Parameters:

• handler (required) The handler decorated with @durable_execution.
• poll_interval (optional) Seconds between internal polling cycles. Defaults to 1.0.

// Class-based input type
LocalDurableTestRunner.create(Class<I> inputType, BiFunction<I, DurableContext, O> handlerFn)

// TypeToken-based input type (for generic types)
LocalDurableTestRunner.create(TypeToken<I> inputType, BiFunction<I, DurableContext, O> handlerFn)

// With a custom DurableConfig
LocalDurableTestRunner.create(Class<I> inputType, BiFunction<I, DurableContext, O> handlerFn, DurableConfig config)

// From a DurableHandler instance (extracts config automatically)
LocalDurableTestRunner.create(Class<I> inputType, DurableHandler<I, O> handler)

Override config or the output type on an existing runner:

LocalDurableTestRunner<I, O> withDurableConfig(DurableConfig config)
LocalDurableTestRunner<I, O> withOutputType(Class<O> outputType)
LocalDurableTestRunner<I, O> withOutputType(TypeToken<O> outputType)

Parameters:

• inputType (required) The input type class or TypeToken.
• handlerFn (required) A BiFunction<I, DurableContext, O> implementing the handler logic.
• config (optional) A DurableConfig. The runner overrides the DurableExecutionClient with its in-memory implementation but preserves all other settings such as custom SerDes.
• handler (optional) A DurableHandler instance. The runner extracts its configuration automatically.

Construction is the whole lifecycle. The opts are the production handler's durable.HandlerOption values, such as durable.WithSerdes. The handler has type durable.Handler[I, O], that is func(durable.Context, I) (O, error).

func NewLocalRunner[I, O any](handler durable.Handler[I, O], opts ...durable.HandlerOption) *LocalRunner[I, O]

Parameters:

• handler (required) The durable handler under test.
• opts (optional) durable.HandlerOption values, applied as in production. The runner supplies its own in-memory execution client.

Returns: *LocalRunner[I, O]

durable::test_util::LocalRunner runs the handler in process. The test_util module requires the SDK's test-util cargo feature, which you enable on a dev-dependency as Install the testing SDK shows.

impl LocalRunner {
    // ...
    pub fn new() -> Self;
    // ...
    pub fn options(mut self, options: crate::Options) -> Self;
    // ...
}

LocalRunner::default() returns the same runner as LocalRunner::new(). Each setting is a builder method that takes the runner and returns it (see LocalDurableTestRunnerSetupParameters). You pass the handler to run, so one runner can run several handlers. The runner needs no setup or teardown.

Parameters:

• options (optional) The production handler's durable::Options. Every setting applies as in production except the transport. The runner ignores sdk_config, lambda_client, and execution_client, and uses its in-memory backend. Defaults to Options::default().

Returns: LocalRunner

The local runner type is DurableTestRunner<TInput, TOutput>. Construct it with the workflow delegate and dispose it with await using:

DurableTestRunner(
    Func<TInput, IDurableContext, Task<TOutput>> handler,
    TestRunnerOptions? options = null)

await using var runner = new DurableTestRunner<object?, string>(
    Workflow,
    new TestRunnerOptions { SkipTime = true });

There is no static setup/teardown. The await using declaration and DisposeAsync() replace the TypeScript setupTestEnvironment/teardownTestEnvironment lifecycle.

Constructor parameters:

• handler (required) A Func<TInput, IDurableContext, Task<TOutput>>, either a method group or an inline (input, ctx) => ... async lambda.
• options (optional) A TestRunnerOptions record. Defaults to a new instance with SkipTime = true.

run(params?: InvokeRequest): Promise<TestResult>

run() drives the full replay loop until the execution completes or fails.

Parameters:

• params (optional) An InvokeRequest object.
  • payload (optional) The input payload to pass to the handler.

Returns: Promise<TestResult>

run(
    input: str | None = None,
    timeout: int = 900,
    function_name: str = "test-function",
    execution_name: str = "execution-name",
    account_id: str = "123456789012",
) -> DurableFunctionTestResult

Parameters:

• input (optional) JSON-encoded input string. Defaults to None.
• timeout (optional) Maximum seconds to wait for completion. Defaults to 900.
• function_name (optional) Function name used internally. Defaults to "test-function".
• execution_name (optional) Execution name used internally. Defaults to "execution-name".
• account_id (optional) Account ID used internally. Defaults to "123456789012".

Returns: DurableFunctionTestResult

Raises: TimeoutError if the execution does not complete within timeout.

// Runs a single invocation (may return PENDING)
TestResult<O> run(I input)

// Drives the full replay loop until SUCCEEDED, FAILED, or PENDING with no
// auto-advanceable operations
TestResult<O> runUntilComplete(I input)

Parameters:

• input (required) The handler input.

Returns: TestResult<O>

Run performs a single invocation and may return PENDING. RunUntilComplete loops, advancing timers and running registered invoke targets between invocations. It returns at a terminal status, when the execution is blocked on a callback or chained invoke, or at the invocation cap.

func (r *LocalRunner[I, O]) Run(event I) (*TestResult, error)
func (r *LocalRunner[I, O]) RunUntilComplete(event I, opts ...RunnerOption) (*TestResult, error)

Parameters:

• event (required) The handler input, of the runner's input type I. The runner encodes it as JSON.
• opts (optional) RunnerOption values. WithMaxInvocations sets the invocation cap, which defaults to DefaultMaxInvocations (100).

Returns: *TestResult and an error. When RunUntilComplete reaches the cap, the result holds the last state, usually PENDING, with CapReached set to true.

CapReached bool

Errors: The error is non-nil, and the result nil, only when the runner itself fails. That happens when the event does not encode as JSON, the invocation returns an error that indicates an SDK or runner bug, or the response does not parse. A handler that returns an error produces a nil error and a result with status FAILED.

pub fn run<E, O, F, Fut>(&self, handler: F, event: E) -> RunHandle<O>
where
    E: Serialize + DeserializeOwned + Send + 'static,
    O: Serialize + DeserializeOwned + Send + 'static,
    F: Fn(E, DurableContext) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = Result<O, BoxError>> + Send;
// ...
pub fn max_invocations(mut self, max: usize) -> Self;

run returns a durable::test_util::RunHandle<O> at once. RunHandle is a future. Awaiting it drives the full replay loop until the execution succeeds or fails, nothing can advance it, or the invocation cap is reached. The run starts when the test first awaits a future of the run, such as the RunHandle.

Parameters:

• handler (required) The durable handler, the function you pass to durable::run. Its event and output types need Serialize and DeserializeOwned.
• event (required) The handler input. The runner encodes it as JSON.
• max (optional) The invocation cap, set with max_invocations. Defaults to 100. A value of 0 counts as 1.

Returns: RunHandle<O>. Awaiting it returns Result<TestResult<O>, TestRunnerError>. When nothing can advance the execution, or the cap is reached, the result has status ExecutionStatus::Running and error_message() says why the run ended.

Errors: Awaiting the handle returns Err(TestRunnerError) only when the runner itself fails. That happens when the event does not encode as JSON (EventSerialization), the output of a succeeded execution does not decode into O (OutputDeserialization), or a response envelope has a status other than SUCCEEDED, FAILED, and PENDING (UnexpectedEnvelope). A handler that returns an error produces Ok with a result whose status is ExecutionStatus::Failed.

Task<TestResult<TOutput>> RunAsync(
    TInput input,
    TimeSpan? timeout = null,
    CancellationToken cancellationToken = default)

RunAsync drives the full replay loop until the workflow reaches a terminal state. It throws InvalidOperationException if the workflow suspends on a callback. Use the StartAsync + WaitForCallbackAsync two-call pattern for callback workflows.

TestResult<string> result = await runner.RunAsync(null);

Parameters:

• input (required) The handler input.
• timeout (optional) Wall-clock timeout for the call. Defaults to TestRunnerOptions.DefaultTimeout (30 seconds).
• cancellationToken (optional) A CancellationToken.

Returns: Task<TestResult<TOutput>>

Not applicable. run() already drives the full replay loop.

Not applicable on the local runner. run() runs a single invocation, runUntilComplete() drives the full loop. The cloud runner exposes startAsync(), see CloudDurableTestRunner.

For a callback or chained invoke, run to PENDING, resolve the pending operation, then call RunUntilComplete again.

run returns the RunHandle at once and drives nothing until the test awaits a future of the run. Before you await the RunHandle, take operation handles from it and await their controls, such as wait_for_data and send_callback (see Drive a callback from an operation). The run moves on only while the test awaits a future of the run, such as the RunHandle or wait_for_data. So await the operation controls first and the RunHandle last.

The local runner supports the async pattern, primarily for callback workflows:

// Start the workflow and return the durable execution ARN
Task<string> StartAsync(
    TInput input, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

// Drive a started workflow to a terminal state
Task<TestResult<TOutput>> WaitForResultAsync(
    string durableExecutionArn, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

StartAsync drives the workflow to its first suspension point and returns the ARN. WaitForResultAsync must be preceded by a StartAsync on the same runner; it throws InvalidOperationException otherwise. Use these together with WaitForCallbackAsync and the SendCallback* methods to drive callback workflows.

getOperation(name: string, index?: number): DurableOperation
getOperationByIndex(index: number): DurableOperation
getOperationByNameAndIndex(name: string, index: number): DurableOperation
getOperationById(id: string): DurableOperation

Parameters:

• name (required) The operation name.
• index (optional) Zero-based index when multiple operations share the same name. Defaults to 0.
• id (required) The unique operation ID.

Returns: DurableOperation

Not available on the runner. Inspect operations through the result: result.get_step(name), result.get_wait(name), result.get_callback(name), result.get_context(name), result.get_invoke(name), result.get_operation_by_name(name), and result.get_all_operations(). See TestResult.

TestOperation getOperation(String name)

Parameters:

• name (required) The operation name.

Returns: TestOperation, or null if not found.

Inspect operations through the result.

func (r *TestResult) Operation(name string) *TestOperation
func (r *TestResult) OperationByNameAndIndex(name string, index int) *TestOperation
func (r *TestResult) OperationByIndex(index int) *TestOperation
func (r *TestResult) OperationByID(id string) *TestOperation
func (r *TestResult) OperationsByType(opType string) []TestOperation

Parameters:

• name (required) The operation name. Operation returns the first match.
• index (required) A zero-based index. For OperationByNameAndIndex it counts operations with that name. For OperationByIndex it counts all operations.
• id (required) The operation's wire ID.
• opType (required) An operation type string, such as "STEP".

Returns: A *TestOperation, or nil if not found. OperationsByType returns a []TestOperation.

Take operation handles from the RunHandle that run returns. A handle names an operation by name, index, or ID, and finds it each time you use the handle. So you can take a handle before the operation exists. After the run, result.operation(name) and result.operations_named(name) find operations by name, result.children(parent) finds the children of an operation, and result.operations() returns the whole history in first-checkpoint order (see Operations).

pub fn operation(&self, name: &str) -> OperationHandle;
// ...
pub fn operation_by_index(&self, index: usize) -> OperationHandle;
// ...
pub fn operation_by_name_and_index(&self, name: &str, index: usize) -> OperationHandle;
// ...
pub fn operation_by_id(&self, id: &str) -> OperationHandle;
// ...
pub fn snapshot(&self) -> Option<TestOperation>;

Parameters:

• name (required) The operation name, matched exactly. operation names the first operation with that name.
• index (required) A zero-based index, in TestResult::operations order. For operation_by_name_and_index it counts operations with that name. For operation_by_index it counts all operations.
• id (required) The unique operation ID.

Returns: An OperationHandle. Its snapshot() returns the operation as it is now, as a TestOperation, or None while no operation matches.

The .NET runner does not expose operation lookups; inspect operations through the returned TestResult<TOutput> instead:

TestStep GetStep(string name)      // throws if not found
TestStep? FindStep(string name)    // null if not found
IReadOnlyList<TestStep> GetSteps(string name)
TestStep GetStepById(string operationId)
IReadOnlyList<TestStep> GetStepsByStatus(string status)
IReadOnlyList<TestStep> GetChildren(TestStep parent)

result.Steps also exposes the full list of recorded operations (excluding the top-level execution). See TestResult.

Callback interaction is on the DurableOperation object. Get a handle with getOperation() and then call waitForData() and sendCallback*() on it. See Drive a callback from an operation.

Drive callbacks from the runner by callback ID. Enumerate the pending callbacks with OpenCallbacks, then resolve one. A failure takes an errorType and an errorMessage string.

func (r *LocalRunner[I, O]) OpenCallbacks() []OpenCallback
func (r *LocalRunner[I, O]) SendCallbackSuccess(callbackID string, payload any) error
func (r *LocalRunner[I, O]) SendCallbackFailure(callbackID, errorType, errorMessage string) error
func (r *LocalRunner[I, O]) SendCallbackHeartbeat(callbackID string) error
func (r *LocalRunner[I, O]) TimeoutCallback(callbackID string) error

type OpenCallback struct {
    CallbackID string
    Name       string
}

SendCallbackSuccess encodes payload as JSON. So a Go string "approved" arrives as "approved" with its quote characters. OpenCallback.Name is the callback operation's name. A WaitForCallback records an unnamed inner callback, so its Name is empty. The WaitForCallback name is on the callback's parent operation.

Answer a callback in one of two ways. Queue a reply on the runner before the run with callback or callback_for, or send one during the run from an operation handle (see Drive a callback from an operation). Both take a durable::test_util::CallbackReply.

pub fn callback(mut self, reply: CallbackReply) -> Self;
// ...
pub fn callback_for(mut self, name: impl Into<String>, reply: CallbackReply) -> Self;

A pending callback is a callback that waits for a reply. Between invocations, the runner visits the pending callbacks in the order they were first checkpointed. It gives each one the first queued callback_for reply that names it, else the first queued callback reply, else nothing. A name matches the callback's own name, or the name of the wait_for_callback that contains it. Queued replies arrive before the virtual clock moves. When the run ends because nothing can advance the execution, the result has status Running, and its error_message() names each queued callback_for reply that matched no callback.

impl CallbackReply {
    pub fn success<T: Serialize>(value: &T) -> Result<Self, BoxError>;
    // ...
    pub fn raw(payload: impl Into<String>) -> Self;
    // ...
    pub fn failure(failure: CallbackFailure) -> Self;
    // ...
    pub fn timeout() -> Self;
    // ...
    pub fn heartbeat_timeout() -> Self;
    // ...
}

• success(value) The callback succeeds with the JSON encoding of value. Returns an error when value does not encode as JSON.
• raw(payload) The callback succeeds with payload unchanged. The handler decodes it with the callback's serdes.
• failure(failure) The callback fails with the error fields of failure.
• timeout() The callback times out with the message Callback timed out.
• heartbeat_timeout() The callback times out with the error type Callback.Heartbeat and the message Callback timed out on heartbeat.

impl CallbackFailure {
    pub fn new(error_type: impl Into<String>, error_message: impl Into<String>) -> Self;
    // ...
    pub fn with_error_data(mut self, error_data: impl Into<String>) -> Self;
    // ...
    pub fn with_stack_trace(mut self, frames: Vec<String>) -> Self;
    // ...
}

CallbackFailure::new sets the error type and message. with_error_data and with_stack_trace add the error data and the stack trace frames. CallbackFailure::default() leaves every field unset.

Callbacks are driven from the runner. After StartAsync, wait for the callback ID, then send success, failure, or a heartbeat:

// Wait for a pending callback and return its ID
Task<string> WaitForCallbackAsync(
    string durableExecutionArn, string? name = null,
    TimeSpan? timeout = null, CancellationToken cancellationToken = default)

// Complete a callback with a success result
Task SendCallbackSuccessAsync<TResult>(
    string callbackId, TResult result, CancellationToken cancellationToken = default)

// Fail a callback
Task SendCallbackFailureAsync(
    string callbackId, ErrorObject? error = null, CancellationToken cancellationToken = default)

// Keep a callback alive
Task SendCallbackHeartbeatAsync(
    string callbackId, CancellationToken cancellationToken = default)

There is no separate "time out" method: to simulate a timeout, fail the callback with an ErrorObject or let the configured callback timeout elapse.

Not applicable. Register a mock handler for the invoked function and let the test drive the real handler path. See Register mock handlers for invoke.

Not applicable.

Resolve a chained invoke by its operation name, or register the target so the invoke runs for real (see the next section).

func (r *LocalRunner[I, O]) CompleteChainedInvoke(name string, payload any) error
func (r *LocalRunner[I, O]) FailChainedInvoke(name, errorType, errorMessage string) error
func (r *LocalRunner[I, O]) TimeoutChainedInvoke(name string) error

Register a target for the invoked function. See Register mock handlers for invoke. An invoke of a function name with no registered target fails the execution, and the result's error_message() names the function.

The .NET SDK does not expose per-invoke completion methods. Instead, register the invoked function's handler on the runner and let the real invoke path run against it. See Register mock handlers for invoke. To make an invoke fail, throw from the registered handler.

// Register a durable function for context.invoke() calls
registerDurableFunction(functionName: string, handler: DurableLambdaHandler): this

// Register a standard Lambda function for context.invoke() calls
registerFunction(functionName: string, handler: Handler): this

Both methods return the runner for chaining.

Not applicable.

Not applicable.

Register the function identifier the handler passes to durable.Invoke. Build the target with DurableFunction for a durable handler or PlainFunction for a one-shot handler. Registered targets may invoke other registered identifiers up to MaxInvokeDepth levels deep.

func (r *LocalRunner[I, O]) RegisterFunction(functionID string, fn Function)
func DurableFunction[I, O any](handler durable.Handler[I, O], opts ...durable.HandlerOption) Function
func PlainFunction[I, O any](handler func(context.Context, I) (O, error)) Function
const MaxInvokeDepth = 10

pub fn register_function<I, O, F, Fut>(mut self, name: impl Into<String>, function: F) -> Self
where
    I: DeserializeOwned + Send + 'static,
    O: Serialize + Send + 'static,
    F: Fn(I) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = Result<O, BoxError>> + Send + 'static;
// ...
pub fn register_durable_function<E, O, F, Fut>(
    mut self,
    name: impl Into<String>,
    handler: F,
) -> Self
where
    E: Serialize + DeserializeOwned + Send + 'static,
    O: Serialize + DeserializeOwned + Send + 'static,
    F: Fn(E, DurableContext) -> Fut + Send + Sync + 'static,
    Fut: Future<Output = Result<O, BoxError>> + Send;

Both methods return the runner for chaining. name is the function name the handler passes to ctx.invoke, matched exactly. A later registration under the same name replaces the earlier one. When an invocation suspends, the runner runs the target of each pending invoke once, before the virtual clock moves.

register_function registers a plain function. The runner decodes its input from the invoke payload and encodes its output as JSON. An Err fails the invoke. register_durable_function runs the handler as its own durable execution, with a fresh in-memory backend and a copy of the runner's settings. The runner gives that execution none of its registered functions, queued callback replies, or injected checkpoint failures. So a registered durable target cannot invoke another registered target.

// Register a durable sibling that the workflow invokes with context.InvokeAsync()
DurableTestRunner<TInput, TOutput> RegisterDurableFunction<TPayload, TResult>(
    string functionNameOrArn,
    Func<TPayload, IDurableContext, Task<TResult>> handler)

// Register a plain (non-durable) Lambda sibling, also invoked with context.InvokeAsync()
DurableTestRunner<TInput, TOutput> RegisterFunction<TPayload, TResult>(
    string functionNameOrArn,
    Func<TPayload, ILambdaContext, Task<TResult>> handler)

Both methods return the runner for chaining.

Not applicable.

Not applicable.

To exercise failure and retry, return an error from a step. OmitTokenOnCheckpoint withholds the checkpoint token on the n-th checkpoint call, so the invocation ends PENDING and resumes on the next run. n counts calls from now, starting at 1. A value below 1 panics.

func (r *LocalRunner[I, O]) OmitTokenOnCheckpoint(n int)

These builder methods make the in-memory backend fail or delay checkpoint calls.

pub fn fail_next_checkpoints(self, count: usize) -> Self;
// ...
pub fn fail_checkpoints_after(mut self, skip: usize, count: usize) -> Self;
// ...
pub fn fail_checkpoints_after_retryable(mut self, skip: usize, count: usize) -> Self;
// ...
pub fn withdraw_checkpoints_after(mut self, n: usize) -> Self;
// ...
pub fn checkpoint_latency(mut self, latency: std::time::Duration) -> Self;

• fail_next_checkpoints(count) Rejects the next count checkpoint calls with a non-retryable error and stores nothing for them. The SDK sends no further checkpoint and fails the execution with the error type CheckpointUnrecoverableExecutionError.
• fail_checkpoints_after(skip, count) Lets skip checkpoint calls through, then rejects the next count calls in the same way.
• fail_checkpoints_after_retryable(skip, count) Lets skip checkpoint calls through, then rejects the next count calls with a retryable error. The invocation fails, the runner invokes again, and replay resumes from the stored state.
• withdraw_checkpoints_after(n) Answers checkpoint request n + 1 without a checkpoint token, once. Requests count from 1 across invocations. The backend applies that request, the SDK sends nothing more in that invocation, and the runner invokes again at once.
• checkpoint_latency(latency) Delays each checkpoint response by latency in Tokio time, to expose races. Defaults to zero. It does not move the virtual clock.

One checkpoint fault applies at a time. Each fail_* call replaces the fault that an earlier fail_* call set, so fail_next_checkpoints(count) is the same as fail_checkpoints_after(0, count).

The .NET SDK does not expose checkpoint-manipulation methods. To exercise failure and retry paths, throw from inside a step and assert on TestStep.Attempt and the recorded operation status. See the retry example in Authoring.

Pass { skipTime: true } to setupTestEnvironment(). Both context.wait() delays and step retry delays complete in zero wall-clock time.

Pass skip_time=True to DurableFunctionTestRunner. The runner uses a virtual clock that skips modeled delays instantly. Both context.wait() durations and step retry delays complete in zero wall-clock time. skip_time defaults to True.

runner = DurableFunctionTestRunner(handler=handler, skip_time=True)

Set skip_time=False to assert on real wait durations.

void advanceTime()

runUntilComplete() calls advanceTime() after each invocation. When you call run() directly, call advanceTime() yourself between invocations. advanceTime() marks PENDING step retries as READY and completes STARTED waits without real-time sleeps.

Time is virtual and always skipped. RunUntilComplete advances timer-blocked operations between invocations. CompletePendingTimers fires every pending retry and wait timer at once and reports whether any fired. To check a wait's duration, read WaitDetails.WaitSeconds.

func (r *LocalRunner[I, O]) CompletePendingTimers() bool

Time is virtual and always skipped. The runner keeps a virtual clock in whole seconds that starts at 0 for each run. Between invocations, it moves the clock to the earliest pending wait or retry end and fires every wait and retry due by then, so waits and retries end in time order. Time moves only between invocations. To check a wait's duration, read WaitDetails::duration (see Wait details).

Set SkipTime on TestRunnerOptions. When true (the default), both WaitAsync delays and step/WaitForConditionAsync retry backoffs complete immediately instead of sleeping for real wall-clock time. There is no manual advanceTime() call. RunAsync advances time internally.

await using var runner = new DurableTestRunner<object, string>(
    Workflow,
    new TestRunnerOptions { SkipTime = true });

Set SkipTime = false to assert on real wait durations.

reset(): void

Clears the operation index, wait manager, and operation storage so the runner can be reused across tests.

Create a new DurableFunctionTestRunner instance per test.

Create a new LocalDurableTestRunner instance per test.

Reset discards the checkpoint log, the recorded events, and every open callback and invoke, while keeping the handler, its options, and the registered functions, so one runner serves several cases.

func (r *LocalRunner[I, O]) Reset()

A runner holds only settings, and run borrows it. Each run starts from an empty history and gets its own copy of the queued callback replies, so one runner serves several cases with no reset.

There is no reset(). A runner is single-use and not thread-safe: create a new DurableTestRunner<TInput, TOutput> per test and dispose it with await using.

interface LocalDurableTestRunnerSetupParameters {
  skipTime?: boolean;
  checkpointDelay?: number;
}

Fields:

• skipTime (optional) Install fake timers so retry delays and waits complete instantly. Defaults to false.
• checkpointDelay (optional) Simulated delay in milliseconds on checkpoint API calls. Useful for surfacing race conditions.

DurableFunctionTestRunner(handler, skip_time=True, poll_interval=1.0)

Fields:

• skip_time (optional) Use a virtual clock that skips modeled delays instantly. Defaults to True.
• poll_interval (optional) Seconds between internal polling cycles. Defaults to 1.0.

Not applicable. Configure with withDurableConfig, withOutputType, and advanceTime() on the runner instance.

The only run option is WithMaxInvocations on RunUntilComplete. Handler options come from durable.HandlerOption at construction. At the cap, RunUntilComplete returns its last result with CapReached set to true.

type RunnerOption func(*runnerConfig)
func WithMaxInvocations(n int) RunnerOption
const DefaultMaxInvocations = 100

Configure the runner with builder methods on LocalRunner. Each takes the runner and returns it. These methods set how the in-memory backend pages the execution state:

pub fn single_page(mut self) -> Self;
// ...
pub fn initial_page_size(mut self, size: usize) -> Self;
// ...
pub fn checkpoint_page_size(mut self, size: usize) -> Self;

Methods:

• options(options) The production handler's durable::Options. Defaults to Options::default(). See Create a runner.
• max_invocations(max) The invocation cap. Defaults to 100. See Run the handler.
• single_page() Serves the whole execution state in one page. By default the backend pages the state, as the service does.
• initial_page_size(size) The number of operations in the first page of state that each invocation receives. Defaults to 1. A value of 0 counts as 1.
• checkpoint_page_size(size) The number of stored operations above which a checkpoint response is paged. Defaults to 1. A value of 0 counts as 1.
• checkpoint_latency(latency) The delay of each checkpoint response, in Tokio time. Defaults to zero. See Simulate failures.
• fail_next_checkpoints, fail_checkpoints_after, fail_checkpoints_after_retryable, and withdraw_checkpoints_after Injected checkpoint failures. None by default. See Simulate failures.
• callback and callback_for Queued callback replies. None by default. See Drive callbacks.
• register_function and register_durable_function Invoke targets. None by default. See Register mock handlers for invoke.

Time is always virtual. See Control time.

Configuration lives in the TestRunnerOptions record passed to the constructor:

public sealed record TestRunnerOptions
{
    public bool SkipTime { get; init; } = true;
    public int MaxInvocations { get; init; } = 100;
    public TimeSpan DefaultTimeout { get; init; } = TimeSpan.FromSeconds(30);
    public ILambdaSerializer? Serializer { get; init; }
    public ILoggerFactory? LoggerFactory { get; init; }
    public string DurableExecutionArn { get; init; } // synthetic test ARN by default
}

Fields:

• SkipTime (optional) Complete waits and retry backoffs instantly. Defaults to true (the opposite of the JavaScript SDK, where time-skipping is opt-in).
• MaxInvocations (optional) Maximum handler invocations before throwing TestExecutionLimitException. Defaults to 100.
• DefaultTimeout (optional) Wall-clock timeout per RunAsync/WaitForResultAsync call. Defaults to 30 seconds.
• Serializer (optional) An ILambdaSerializer for result deserialization. Defaults to DefaultLambdaJsonSerializer.
• LoggerFactory (optional) An ILoggerFactory for runtime logging.
• DurableExecutionArn (optional) The ARN used in the test context. Defaults to a synthetic test ARN.

getStatus(): ExecutionStatus | undefined

Returns: ExecutionStatus (SUCCEEDED, FAILED, PENDING, or undefined).

result.status  # InvocationStatus

Type: InvocationStatus (SUCCEEDED, FAILED, PENDING, TIMED_OUT, STOPPED).

ExecutionStatus getStatus()
boolean isSucceeded()
boolean isFailed()

Returns: ExecutionStatus (SUCCEEDED, FAILED, PENDING).

Read the Status field. It is one of three ExecutionStatus values. Compare it against the constants, for example result.Status == durabletest.Succeeded.

Status ExecutionStatus

impl<O> TestResult<O> {
    // ...
    pub fn status(&self) -> ExecutionStatus;
    // ...
    pub fn is_success(&self) -> bool;
    // ...
    pub fn is_failure(&self) -> bool;
    // ...
    pub fn is_suspended(&self) -> bool;
    // ...
}

Returns: status() returns a durable::test_util::ExecutionStatus (see Execution status). is_success() is true for Succeeded. is_failure() is true for Failed, TimedOut, and Stopped. is_suspended() is true for Running. Under LocalRunner, a run that ends because nothing can advance the execution, or because it reached the invocation cap, has status Running.

InvocationStatus Status { get; }
bool IsSucceeded { get; }   // Status == InvocationStatus.Succeeded
bool IsFailed { get; }      // Status == InvocationStatus.Failed

Type: InvocationStatus (Succeeded, Failed, Pending). There is no separate execution-status enum in .NET; the cloud runner maps the service's finer terminal states (FAILED, TIMED_OUT, STOPPED) onto InvocationStatus.Failed.

getResult(): TResult | undefined

Returns: The deserialized execution output, or undefined if not available.

Throws: The execution error if the execution failed.

result.result  # str | None

The raw JSON-encoded result payload.

<T> T getResult(Class<T> resultType)
<T> T getResult(TypeToken<T> resultType)
O getResult()  // requires withOutputType() to be set

Returns: The deserialized execution output.

Throws: IllegalStateException if the execution did not succeed.

RawResult holds the JSON result when the status is SUCCEEDED. Deserialize it with the package generic ResultAs[O], which returns an error if the execution did not succeed.

RawResult string
func ResultAs[O any](r *TestResult) (O, error)

pub fn output(&self) -> Option<&O>;
// ...
pub fn into_output(self) -> Option<O>;

Returns: The handler output, already decoded into the handler's output type O, when the status is Succeeded, and None otherwise. output() borrows it and into_output() takes it.

Errors: When the output of a succeeded execution does not decode into O, awaiting the RunHandle returns Err(TestRunnerError::OutputDeserialization).

TOutput? Result { get; }

The deserialized execution output when Status is InvocationStatus.Succeeded; otherwise the default value for TOutput. The result type is fixed at the runner's TOutput type parameter, so no per-call type argument is needed. Call EnsureSucceeded() first if you want a failed run to throw before you read Result.

result.EnsureSucceeded();
Assert.Equal("hello", result.Result);

getError(): TestResultError

Returns: A TestResultError object.

Throws: If the execution succeeded.

Error holds a *TestError when the status is FAILED. This is durabletest's own error type, not the SDK's durable.ErrorObject.

Error *TestError

pub fn error(&self) -> Option<&crate::WireError>;
// ...
pub fn error_type(&self) -> Option<&str>;
// ...
pub fn error_message(&self) -> Option<&str>;

Returns: error() returns the error as a durable::WireError (see TestResultError), or None when the execution succeeded. When the execution failed, it is the recorded error. While the status is Running, it says why the run ended. error_type() and error_message() read the same record. Under LocalRunner, a failure recorded with no error type reads Error.

ErrorObject? Error { get; }

The error when Status is InvocationStatus.Failed; otherwise null. ErrorObject comes from Amazon.Lambda.DurableExecution and exposes ErrorType, ErrorMessage, ErrorData, and StackTrace.

Assert.True(result.IsFailed);
Assert.NotNull(result.Error);

getOperations(params?: { status: OperationStatus }): DurableOperation[]

Parameters:

• params (optional) Filter by OperationStatus.

Returns: Array of DurableOperation.

result.operations               # list[Operation], top-level only
result.get_all_operations()     # list[Operation], including nested

# Typed lookup by name
result.get_step(name: str) -> StepOperation
result.get_wait(name: str) -> WaitOperation
result.get_context(name: str) -> ContextOperation
result.get_callback(name: str) -> CallbackOperation
result.get_invoke(name: str) -> InvokeOperation
result.get_execution(name: str) -> ExecutionOperation
result.get_operation_by_name(name: str) -> Operation

Raises: DurableFunctionsTestError if the operation is not found.

List<TestOperation> getOperations()
List<TestOperation> getSucceededOperations()
List<TestOperation> getFailedOperations()
TestOperation getOperation(String name)

getOperation(name) returns null if not found.

Operations lists every operation the execution checkpointed, in checkpoint order. It includes nested operations and excludes the execution operation. A nested operation's ParentID names its parent. To filter by status, iterate and compare Status. OperationsByType filters by type string.

Operations []TestOperation
func (r *TestResult) OperationsByType(opType string) []TestOperation

pub fn operations(&self) -> &[TestOperation];
// ...
pub fn operation(&self, name: &str) -> Option<&TestOperation>;
// ...
pub fn operations_named<'a>(
    &'a self,
    name: &'a str,
) -> impl Iterator<Item = &'a TestOperation> + 'a;
// ...
pub fn children<'a>(
    &'a self,
    parent: &'a TestOperation,
) -> impl Iterator<Item = &'a TestOperation> + 'a;

operations() lists every operation the execution checkpointed, in first-checkpoint order. It includes nested operations and excludes the execution operation. To filter by status, filter the slice, for example result.operations().iter().filter(|op| op.status() == durable::OperationStatus::Succeeded).

Parameters:

• name (required) The operation name, matched exactly. operation returns the first match, and operations_named returns every match.
• parent (required) An operation of this result. children returns the operations whose parent is parent.

Returns: A slice or an iterator of TestOperation. operation returns None when no operation has the name.

IReadOnlyList<TestStep> Steps { get; }   // all operations except the top-level execution

TestStep GetStep(string name)                 // throws if not found
TestStep? FindStep(string name)               // null if not found
IReadOnlyList<TestStep> GetSteps(string name) // all matches (parallel branches, map items)
TestStep GetStepById(string operationId)
IReadOnlyList<TestStep> GetStepsByStatus(string status)  // pass OperationStatus constants
IReadOnlyList<TestStep> GetChildren(TestStep parent)

Filter Steps by kind with LINQ, e.g. result.Steps.Where(s => s.Kind == OperationKind.Step). Use the OperationStatus string constants (e.g. OperationStatus.Succeeded) with GetStepsByStatus.

Not available on the test result.

Events is the execution's history event sequence. EventTypes returns the event type names in order. The local runner synthesizes the events and leaves fields it has no source for unset.

Events []types.Event
func (r *TestResult) EventTypes() []string

pub fn history_events(&self) -> &[Event];

Event is the service model type durable::lambda_types::Event, and event.event_type() returns its durable::lambda_types::EventType. CloudRunner returns the events of GetDurableExecutionHistory unchanged. LocalRunner synthesizes the events with the same service model types and order, with one InvocationCompleted event for each invocation. LocalRunner moves time only between invocations, so a local run can take more invocations, and record more InvocationCompleted events, than the same execution takes on Lambda. TestOperation::events() returns the events of one operation (see Common accessors).

The .NET TestResult<TOutput> does not expose raw history events. Assert on the folded operations through Steps and the TestStep accessors instead. (Internally the cloud runner reconstructs operations from the history event stream, but that stream is not surfaced on the result.)

getInvocations(): Invocation[]

Useful for asserting on the number of Lambda re-invocations the test runner drove.

Not available on the test result.

Not available on the test result.

Invocations records one entry per completed invocation. Both runners populate it, so a cross-backend test can assert on len(result.Invocations).

Invocations []TestInvocation

type TestInvocation struct {
    RequestID string
    StartTime time.Time
    EndTime   time.Time
    Error     *TestError
}

pub fn invocation_count(&self) -> usize;
// ...
pub fn invocations(&self) -> &[TestInvocation];

invocations() holds one TestInvocation for each InvocationCompleted history event, in history order. Under LocalRunner, invocation n, counting from 1, has the request ID local-invocation-{n}, and the list has invocation_count() records. Under CloudRunner, invocation_count() counts the InvocationCompleted events, or the number of polls when the history holds no such event.

impl TestInvocation {
    // ...
    pub fn start_time(&self) -> Option<std::time::SystemTime>;
    // ...
    pub fn end_time(&self) -> Option<std::time::SystemTime>;
    // ...
    pub fn request_id(&self) -> Option<&str>;
    // ...
    pub fn error(&self) -> Option<&crate::WireError>;
    // ...
}

When an InvocationCompleted event omits its details, start_time(), end_time(), and request_id() return None. A time also returns None when its timestamp lies outside the range of SystemTime. error() is None for an invocation that returned a SUCCEEDED or PENDING result. For a FAILED result it holds the result's error. Under LocalRunner, an invocation fault, such as a retryable checkpoint failure, also sets error(). Its error type is None, and its message is the fault's text.

int? InvocationCount { get; }

The number of handler invocations the local runner used to drive the workflow. It is null when not tracked. The cloud runner never tracks it, so do not assert on InvocationCount in tests intended to run against both backends.

print(config?: { parentId?: boolean; name?: boolean; type?: boolean; ... }): void

Writes a formatted table of operations to stdout.

Not applicable.

Not applicable.

FormatTree renders the operations as an indented tree. WriteTree writes the same text to an io.Writer. Both take optional columns, and DefaultTreeColumns returns the default set.

func (r *TestResult) FormatTree(columns ...TreeColumn) string
func (r *TestResult) WriteTree(w io.Writer, columns ...TreeColumn) error
func DefaultTreeColumns() []TreeColumn

pub fn display_with(&self, columns: PrintColumns) -> impl std::fmt::Display + '_;

TestResult implements Display, which prints a table of the operations with every column, so println!("{result}") writes it to stdout. display_with prints only the columns that columns enables.

pub struct PrintColumns {
    pub parent_id: bool,
    pub name: bool,
    pub kind: bool,
    pub sub_type: bool,
    pub status: bool,
    pub start_time: bool,
    pub end_time: bool,
    pub duration: bool,
}

PrintColumns::default() enables every column. Set fields to false to hide columns. The struct is #[non_exhaustive], so code outside the SDK builds it with default(). The columns, in order, are parentId, name, type, subType, status, startTime, endTime, and duration. The fields parent_id, name, kind, sub_type, status, start_time, end_time, and duration enable them.

The table has a header line and one line per operation, with the cells separated by | and a space on each side. Times print as ISO 8601 UTC with three fractional digits. The duration prints in whole milliseconds, such as 1000ms. An absent value prints -. A result with no operations prints No operations found.

The .NET SDK does not expose a pretty-print method on the result. Iterate result.Steps and format them yourself, e.g. with a foreach over Name, Kind, and Status.

Uses ErrorObject from the main SDK:

@dataclass
class ErrorObject:
    error_message: str | None
    error_type: str | None

Uses ErrorObject from software.amazon.awssdk.services.lambda.model:

ErrorObject.errorMessage()  // String
ErrorObject.errorType()     // String

The result error is TestError. It carries Type, Message, ErrorData, and StackTrace. It is distinct from the SDK's durable.ErrorObject.

type TestError struct {
    Type       string
    Message    string
    ErrorData  string
    StackTrace []string
}

impl WireError {
    // ...
    pub fn error_type(&self) -> Option<&str>;
    // ...
    pub fn error_message(&self) -> Option<&str>;
    // ...
    pub fn error_data(&self) -> Option<&str>;
    // ...
    pub fn stack_trace(&self) -> &[String];
    // ...
}

The result error is durable::WireError, the type the SDK also returns from OperationError::wire(). Its fields are private, so a test compares the accessors. stack_trace() is an empty slice when no frames were recorded. Display writes the type and the message as type: message, either one alone when the other is absent, or unknown error when both are absent.

Uses ErrorObject from Amazon.Lambda.DurableExecution:

public sealed class ErrorObject
{
    public string? ErrorType { get; set; }
    public string? ErrorMessage { get; set; }
    public string? ErrorData { get; set; }
    public IReadOnlyList<string>? StackTrace { get; set; }
}

Every operation type inherits these fields from the base Operation dataclass:

operation.operation_id: str
operation.operation_type: OperationType
operation.status: OperationStatus
operation.name: str | None
operation.parent_id: str | None
operation.sub_type: OperationSubType | None
operation.start_timestamp: datetime | None
operation.end_timestamp: datetime | None

TestOperation exposes public fields and an IsTerminal method. Status, Type, and SubType are strings. A detail pointer is non-nil only when the operation is of that kind. Child nesting is through ParentID.

type TestOperation struct {
    ID        string
    Name      string
    Status    string
    Type      string
    SubType   string
    ParentID  string
    StartTime time.Time
    EndTime   time.Time
    StepDetails     *TestStepDetails
    CallbackDetails *TestCallbackDetails
    InvokeDetails   *TestInvokeDetails
    ContextDetails  *TestContextDetails
    WaitDetails     *TestWaitDetails
}
func (o *TestOperation) IsTerminal() bool

durable::test_util::TestOperation is a copy of one operation record, read through accessor methods.

impl TestOperation {
    // ...
    pub fn id(&self) -> &str;
    // ...
    pub fn events(&self) -> &[Event];
    // ...
    pub fn kind(&self) -> OperationKind;
    // ...
    pub fn sub_type(&self) -> Option<&str>;
    // ...
    pub fn status(&self) -> OperationStatus;
    // ...
    pub fn succeeded(&self) -> bool;
    // ...
    pub fn failed(&self) -> bool;
    // ...
    pub fn result(&self) -> Option<&str>;
    // ...
    pub fn result_json<T: DeserializeOwned>(&self) -> Result<Option<T>, serde_json::Error>;
    // ...
    pub fn is_wait_for_callback(&self) -> bool;
    // ...
    pub fn wait_duration(&self) -> Option<std::time::Duration>;
    // ...
    pub fn error(&self) -> Option<&crate::WireError>;
    // ...
    pub fn error_type(&self) -> Option<&str>;
    // ...
    pub fn error_message(&self) -> Option<&str>;
    // ...
    pub fn name(&self) -> Option<&str>;
    // ...
    pub fn parent_id(&self) -> Option<&str>;
    // ...
    pub fn start_time(&self) -> Option<std::time::SystemTime>;
    // ...
    pub fn end_time(&self) -> Option<std::time::SystemTime>;
    // ...
    pub fn details(&self) -> TestOperationDetails<'_>;
    // ...
}

• id() The unique operation ID.
• events() The history events of this operation, in history order.
• kind() The durable::OperationKind (see Operation type).
• sub_type() The sub-type, such as "Step" or "WaitForCallback", or None. The constants of durable::OperationSubType hold the built-in values.
• status() The durable::OperationStatus (see Operation status). succeeded() is true for Succeeded, and failed() is true for Failed.
• result() The serialized result, JSON with the default serdes. Under CloudRunner, a result over the history's inline size limit is None.
• result_json::<T>() The result decoded from JSON into T. It returns Ok(None) when result() is None, and the serde_json::Error when the result does not decode into T.
• is_wait_for_callback() true for the Context operation of a wait_for_callback, whose sub-type is WaitForCallback.
• wait_duration() The recorded duration of a wait, as WaitDetails::duration() returns it, or None for an operation of another kind.
• error(), error_type(), and error_message() The recorded error (see TestResultError).
• name() The operation name, or None for an unnamed operation.
• parent_id() The ID of the operation that contains this one, or None for a top-level operation. TestResult::children returns an operation's children.
• start_time() and end_time() The start and end times. end_time() is None until the operation ends. Under LocalRunner, each time is the run's start time plus virtual seconds.
• details() The details of the operation's kind.

To test for a callback, compare op.kind() == durable::OperationKind::Callback. To test for a wait_for_callback, call op.is_wait_for_callback().

details() returns the variant of TestOperationDetails that matches kind():

pub enum TestOperationDetails<'a> {
    Context(&'a ContextDetails),
    Step(&'a StepDetails),
    Wait(&'a WaitDetails),
    Callback(&'a CallbackDetails),
    ChainedInvoke,
}

The enum is #[non_exhaustive], so a match on it needs a _ arm.

The docs "Operation" type maps to TestStep in .NET. Common accessors:

string Id { get; }
string? Name { get; }
string? ParentId { get; }
OperationKind Kind { get; }              // Step, Wait, Callback, ChainedInvoke, Context, Execution
string? SubKind { get; }                 // e.g. "Parallel", "Map", "WaitForCallback"
string Status { get; }                   // compare against OperationStatus constants
int Attempt { get; }                     // 1-based for steps, 0 for other kinds
DateTimeOffset? StartedAt { get; }
DateTimeOffset? EndedAt { get; }
TimeSpan? Duration { get; }
IReadOnlyList<TestStep> Children { get; }