Build a graph failure test matrix

Cross node type with failure timing

Classify each node as pure computation, model decision, repeatable read, durable state write, external side effect, or human gate. Then test failure before the node begins, while it is running, after its effect occurs but before confirmation is saved, and after confirmation. The last two are distinct because a timeout does not prove a write failed. Add failures in dependencies: malformed tool output, stale retrieval, unavailable model, full checkpoint store, revoked credential, and a human response arriving after cancellation. A matrix prevents teams from writing one generic retry test and assuming it covers every edge. Rows describe nodes or transitions; columns describe timing, dependency condition, expected durable state, retry policy, visible status, and required operator action.

Test state and path invariants

For each case, assert more than the final message. Check that the graph follows an allowed edge, preserves schema-valid state, never loses an approved proposal, and does not advance from attempted to confirmed without external evidence. Define invariants such as at most one confirmed payment per operation ID, no send edge without a matching approval hash, and no terminal success while required artifacts are absent. LangGraph documents fresh checkpointers for tests, direct node testing, and partial execution by seeding state around selected nodes. Those mechanisms enable controlled tests; the application must supply its own invariants and fault injection. Keep model responses deterministic with stubs when testing graph mechanics, then run separate probabilistic cases for routing quality.

Worked example: a hypothetical publication graph

A hypothetical publication graph researches a topic, drafts an article, requests editor approval, uploads media, and publishes. The matrix injects a research timeout, malformed citation artifact, rejected draft, approval after cancellation, media upload that succeeds before its receipt is lost, publish timeout with unknown remote state, and checkpoint failure after confirmed publication. Expected behavior differs: research may retry within budget; malformed citations return to research; rejection creates a new immutable draft; late approval is ignored; unknown upload and publish states reconcile against the remote service before retrying; checkpoint failure after publication must not publish again. The test uses fake services with operation IDs and queryable receipts. No live article is published, and success requires one visible terminal state plus a trace of the chosen recovery.

Include observability and recovery drills

A graph can preserve data yet remain inoperable if no one can determine its state. Assert that every injected failure emits a sanitized event with run, node, operation, attempt, and reason identifiers, and that dashboards distinguish waiting, failed, cancelled, unknown, and completed. Test the logging system's own failure without dumping raw prompts as a fallback. Exercise restart from each durable checkpoint using production-like storage, because in-memory checkpointers do not establish restart behavior; LangGraph explicitly distinguishes in-memory from persistent options. Finally, give an operator only the run record and documented procedure. They should be able to reconcile an ambiguous side effect, resume a safe node, or terminate the run without editing storage manually. A matrix is complete when expected recovery is executable, not when every cell merely says error handled.

LangGraph testing guide ↗

LangGraph persistence guide ↗

Maintain the matrix with the graph

Review uncovered cells whenever a node, tool, approval type, persistence layer, or external service is introduced. A topology change alters the failure surface even when existing unit tests stay green. Require each new consequential edge to name its ambiguous state and recovery test before it is enabled.