# Model-based testing

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

Model-based testing describes expected behavior as a small model. It generates action sequences and compares the real system with the model after each step.
It suits anything with history: sessions, retries, lifecycles.

[David Khourshid](/lore/david-khourshid) described the approach with state machines in [Model-Based Testing in React with State Machines](https://css-tricks.com/model-based-testing-in-react-with-state-machines/). XState builds it into `xstate/graph`: `createTestModel` wraps a machine, and `getShortestPaths` turns it into test paths. "Path generation enables model-based testing - generating test cases directly from your state machine." [Graph & Paths](https://stately.ai/docs/graph)

Effect 4's `Arbitrary.array` generates command sequences. Its documentation uses a state machine as the example, and failed sequences shrink: the generator removes irrelevant commands to reduce the failing sequence. [Arbitrary.ts](https://github.com/Effect-TS/effect/blob/67ba4e46a11ccda0b6761578bfd22c04ae00167d/packages/effect/src/Arbitrary.ts)

In rat-stack, [the visitor identity model](https://github.com/joelhooks/rat-stack/blob/main/packages/events/test/visitor.model.test.ts) generates visits from three devices.
Visits may keep or drop the cookie. Visits also cross day boundaries.

A persistent id survives every visit that keeps its cookie. A daily id stays stable within a day and sets no cookie.
It never repeats on a later day. Making the daily hash ignore the day broke the model at once.

Machines in this repo are [lifecycles](/lore/lifecycles-are-machines), so each one is a ready-made test model. See [property-based testing](/lore/property-based-testing) for single-input rules.

See also: [Tests through supplied services](/lore/tests-that-earn-their-place) and [recovery needs model tests](/lore/recovery-needs-model-tests).

## Sources

1. [Effect Arbitrary: array shrinking. Effect 4.1.2.](https://github.com/Effect-TS/effect/blob/506eef143bcc1750ce58920aac1e45da7265d103/packages/effect/src/Arbitrary.ts#L450-L466)
   GitHub Effect-TS/effect. Array shrinking tries block removal and element shrinks; bounded shrinking does not guarantee a globally minimal failure. Accessed 2026-11-13.

2. [Model-Based Testing in React with State Machines](https://css-tricks.com/model-based-testing-in-react-with-state-machines/)
   David Khourshid · CSS-Tricks. Testing article; used for checking action sequences against a model. Accessed 2026-10-01.

3. [Graph & Paths](https://stately.ai/docs/graph)
   David Khourshid · Stately docs. Graph docs; used for generated paths from XState machines. Accessed 2026-10-01.

4. [Effect contributors. 2026. Arbitrary. Effect 4.0.0.](https://github.com/Effect-TS/effect/blob/67ba4e46a11ccda0b6761578bfd22c04ae00167d/packages/effect/src/Arbitrary.ts)
   GitHub Effect-TS/effect. Arbitrary API; used for generated and shrinking command sequences. Accessed 2026-10-01.

5. [rat-stack/packages/events/test/visitor.model.test.ts at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/packages/events/test/visitor.model.test.ts)
   GitHub joelhooks/rat-stack. Visitor model test; used for identity across cookies, devices, and days. Accessed 2026-10-01.

## Linked from

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- Agents explore, tests remember → Let agent users explore scenarios; turn a good bug reproduction into a repeatable test. → [Read page](https://ratstack.sh/lore/agents-explore-tests-remember)

- Analytics → One event per HTTP request, stored unchanged for queries to select and interpret later. → [Read page](https://ratstack.sh/systems/analytics)

- Capture first, shape later → Store events without rejecting them for an evolving event shape, then decide their shape when you query. → [Read page](https://ratstack.sh/lore/capture-first)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Choose the check that can catch the failure → Use the testing ladder to choose between lint, types, behavior tests, runtime integration, and deployed checks. → [Read page](https://ratstack.sh/lore/testing-ladder)

- Code snippets quote a pinned source → Shipped design brief: pinned Git objects, typed diagnostics, and one build-only snippet model for both views. → [Read page](https://ratstack.sh/lore/code-snippets)

- David Khourshid → David Khourshid teaches state machines with XState and argues for model-based and property-based testing. → [Read page](https://ratstack.sh/lore/david-khourshid)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Implicit state machines → Every app runs state machines; the risky ones are scattered across flags, conditions and loops where nobody can list the transitions. → [Read page](https://ratstack.sh/lore/implicit-state-machines)

- model-a-protocol → Check a protocol with a small TLA+ model before you build or change it. Use when steps can interleave or die halfway, such as a crash between two writes, a retry after an unknown outcome, an alarm or sweep that redrives work, or two writers on one record. Also use when asked "can this race?", "what if it dies here?", or "model this", or before a durability design review. → [Read page](https://ratstack.sh/skills/model-a-protocol)

- Property tests for the UI with Bombadil → Check search counts and video consent with generated browser actions, then choose the right test layer for server races. → [Read page](https://ratstack.sh/resources/bombadil-ui-property-tests)

- Property-based testing → State a rule that must hold for every input, then let a generator search for a failing input. → [Read page](https://ratstack.sh/lore/property-based-testing)

- Rat Stack lore | rat-stack → Short, source-grounded notes on the ideas and decisions behind rat-stack. → [Read page](https://ratstack.sh/lore)

- Recovery needs model tests → Test sequences of failures and recoveries against explicit invariants. → [Read page](https://ratstack.sh/lore/recovery-needs-model-tests)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)

- test-behaviour → Pick the test shape that proves a behaviour. Use when you ask "how do I test this?", add a test, test a domain rule, a lifecycle, a retry, a session, a UI interaction, a timer, or a race, or review a test that might be tautological. → [Read page](https://ratstack.sh/skills/test-behaviour)

- Tests prove behavior through supplied services → Supply services through Layers, choose properties or models for domain rules, and reject tests that cannot detect broken behavior. → [Read page](https://ratstack.sh/lore/tests-that-earn-their-place)

- UI behaviour is a scene → A Foldkit Scene drives update, view, and subscriptions with input and time as plain data, then asserts on what the view shows. → [Read page](https://ratstack.sh/lore/ui-behaviour-is-a-scene)
