User manual

Read How Counterfact fits together for specifications, handlers, contexts, scenarios, API groups, and shared stores.

Build a useful local API, then add the behavior your client needs. Each chapter shows how to use a feature with examples.

New to Counterfact? Start with Generate an API from OpenAPI, then follow the first ten minutes. For exact signatures and options, use the API reference.

Choose guides by task in Find your workflow. Additional resources: FAQ, comparison, TypeScript native mode, and telemetry and privacy.

Start a working API

• Generate an API from OpenAPI — Start a local HTTP API from a specification.
• Automatic sample responses — Get schema-derived responses and select named examples.
• Build without OpenAPI — Write routes before a specification exists.
• Swagger UI — Browse operations and send requests in the browser.

Define request and response behavior

• Custom route handlers — Read typed request data and implement HTTP operations.
• Response building — Choose status codes, bodies, headers, cookies, and media types.
• Streaming responses — Return incremental events and records.
• Failures, latency, and edge cases — Exercise loading, error, retry, and empty states.
• Request and response validation — Understand which contract mismatches are checked.
• Middleware — Apply behavior across a route subtree.

Model state and workflows

• Stateful contexts — Let later requests observe earlier actions.
• Nested and connected contexts — Divide state by route subtree and connect contexts.
• Shared application store — Share domain data across API groups.
• Scenario scripts — Apply reusable state changes and startup setup.

Explore a running simulation

• Hot reload — Change behavior while preserving live state.
• Interactive REPL — Inspect and steer the running API from a terminal.
• Request builder — Construct, inspect, reuse, and send API requests.

Work with evolving APIs

• Proxying and hybrid simulation — Combine local handlers with upstream services.
• Multiple APIs — Serve several specifications on one listener.
• API versioning — Serve versions side by side with version-aware types.
• OpenAPI overlays — Adapt a specification without editing its source.
• Regeneration and generated code — Refresh contracts while preserving editable routes.

Integrate with development tools

• Programmatic use and tests — Start, inspect, reset, seed, and stop a simulator from code.
• HTTP Admin API — Inspect contexts, routes, and proxy settings over HTTP.

Complete workflows

• Payment decline, retry, permissions, and reset — connect a small state model to real HTTP assertions.
• Contract-change check — regenerate types, observe a compiler error, and fix the handler.
• Reproducible hybrid proxy — check local/upstream selection into source control.
• AI-assisted workflows — give an agent a specific task and check its work.