Docket.Test (docket v0.1.0)

Copy Markdown View Source

Inline test runtime: executes graph transitions in the calling process using the same loop, algorithm, validation, reducer, and checkpoint-building code as backend execution vehicles.

The inline runtime is not a second interpreter - only the driver differs. Use it for graph semantics, checkpoint ordering, reducers, guards, interrupts, and failure policy. Backend tests cover durable lifecycle, crash recovery, claims, scheduling, and supervised task execution.

Options

All helpers accept:

  • :executor - Docket.Executor module (default Docket.Executor.Local)
  • :executor_opts - keyword list passed through to the executor
  • :context - application context passed to nodes and test sinks
  • :clock, :id_generator, :sleeper - determinism injection points; the sleeper serves each committed retry park's wait, and the helpers then treat the parked deadline as reached without re-reading the clock
  • :max_supersteps - runtime default when the graph declares no policy
  • :max_steps - stop driving after this many committed supersteps
  • :run_id - explicit run ID for the fresh run document
  • :metadata - application metadata map for the fresh run document

Checkpoints are returned in order so ordinary semantic tests can assert a complete transition sequence without Process.sleep/1.

Return shape for all helpers:

{:ok, Docket.Run.t(), [Docket.Checkpoint.t()]}
| {:error, Docket.Error.t(), [Docket.Checkpoint.t()]}

Summary

Functions

Resolves an open interrupt inline, then continues driving the run.

Resumes a saved Docket.Run through the same durable barrier used by run_inline/3, then continues execution.

Compiles (when given a Docket.Graph), builds a fresh run from input, initializes through the same processless transition barrier used by backend vehicles, and executes supersteps until the run is terminal, waiting, or the step limit is reached.

Drives exactly one committed transition and returns the updated run with the accepted checkpoints from that transition.

Functions

resolve_interrupt_inline(run, interrupt_id, value, opts \\ [])

Resolves an open interrupt inline, then continues driving the run.

Requires the graph via :graph or :runtime_graph in opts.

resume_inline(graph_or_runtime_graph, run, opts \\ [])

Resumes a saved Docket.Run through the same durable barrier used by run_inline/3, then continues execution.

Requires graph.id == run.graph_id and a matching graph hash. A terminal run is returned unchanged without restarting execution.

run_inline(graph_or_runtime_graph, input, opts \\ [])

Compiles (when given a Docket.Graph), builds a fresh run from input, initializes through the same processless transition barrier used by backend vehicles, and executes supersteps until the run is terminal, waiting, or the step limit is reached.

step_inline(run, opts \\ [])

Drives exactly one committed transition and returns the updated run with the accepted checkpoints from that transition.

Requires the graph via :graph or :runtime_graph in opts (a run document does not carry its graph). A :created run performs initialization only; a :running run commits one superstep; :waiting and terminal runs return unchanged.