# Property-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).

An example test checks one input you picked. A property test states a rule that must hold for every input. It generates many inputs and shrinks a failing input to a small counterexample.

[The bounded shrink search may return the original failing input.](https://github.com/Effect-TS/effect/blob/506eef143bcc1750ce58920aac1e45da7265d103/packages/effect/src/Arbitrary.ts#L287-L297)

Effect 4 ships its own engine in `effect/Arbitrary`. `Arbitrary.schema` derives a generator from an Effect `Schema`. The same schema defines the [capability's contract](/systems/capabilities) and generates its test inputs. `Arbitrary.checkEffect` checks a pure or effectful property and "shrinks the first falsification." [Arbitrary.ts](https://github.com/Effect-TS/effect/blob/67ba4e46a11ccda0b6761578bfd22c04ae00167d/packages/effect/src/Arbitrary.ts)

`@effect/vitest` exposes it as `it.prop` and `it.effect.prop`.

The [capture-first](/lore/capture-first) events cartridge is tested this way. For any generated request:

- Exactly one event is recorded.
- The response body and status are preserved.
- Persistent HTML may add the visitor cookie.
- The request body never reaches the event.
  For any query string, credential and email keys never survive. A failing sink does not change the response body or status. [Analytics](/systems/analytics) documents cookie behavior and what the checks establish about storage in Basin.

A property earns its place only if breaking the code breaks it. When first written, the events tests did not fail when `token` was removed from the sensitive-key list. The property compared the filter with the same function it was testing.

A second property with an independent list of sensitive keys closed the gap. The failure shrank to a single input, `"secret": "token"`. See [tests that earn their place](/lore/tests-that-earn-their-place).

For sequences of actions, use [model-based testing](/lore/model-based-testing).

For rendered search counts and video-player consent, read [Property tests for the UI with Bombadil](/resources/bombadil-ui-property-tests).

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

## Sources

1. [Effect Arbitrary: Falsified result. Effect 4.1.2.](https://github.com/Effect-TS/effect/blob/506eef143bcc1750ce58920aac1e45da7265d103/packages/effect/src/Arbitrary.ts#L287-L297)
   GitHub Effect-TS/effect. The bounded shrink search returns its best failing value, which may equal the initial input. Accessed 2026-11-13.

2. [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 inputs and shrinking failures. Accessed 2026-10-01.

3. [rat-stack/packages/events/test at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/tree/main/packages/events/test)
   GitHub joelhooks/rat-stack. Events properties; used for capture invariants over generated requests. Accessed 2026-10-01.

4. [David K 🎹 on X: "@joelhooks I need to get you on the MBT/PBT train" / X](https://x.com/davidkpiano/status/2105670489091834297)
   David Khourshid. Public reply; used for David's invitation to adopt property-based testing. Accessed 2026-10-01.

## Lore on this page

- [A cartridge owns one job and its resources](/lore/cartridges)

## Linked from

- Accumulate independent errors before writing output → Check every independent job before any job writes an asset. → [Read page](https://ratstack.sh/lore/accumulate-independent-errors)

- 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)

- Durability starts with a recovery record → A reading order for storage, replay, worker ownership, overload, and recovery tests. → [Read page](https://ratstack.sh/lore/durability)

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

- Learn mode presents concepts at useful depths → An agent presents source-derived concepts during real work and keeps learning events in a private local log. → [Read page](https://ratstack.sh/systems/learn)

- 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)

- Model-based testing → Describe what a system should do as a small model, generate action sequences, and check the real system against the model. → [Read page](https://ratstack.sh/lore/model-based-testing)

- 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)

- 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)

- Schemas define the boundary → Define accepted data with Schema, decode unknown input before dispatch, and encode results through the declared contract. → [Read page](https://ratstack.sh/lore/schemas-define-the-boundary)

- Shared schemas need a transition period → Keep old and new representations usable while consumers migrate. → [Read page](https://ratstack.sh/lore/schema-changes-need-a-transition)

- 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)

- Tokenize the whole file before slicing → Select lines after tokenization so preceding code still guides recognition of multiline strings and comments. → [Read page](https://ratstack.sh/lore/tokenize-before-slicing)

- uncomplect → Find responsibilities that a rat-stack design combines, separate them into capabilities, cartridges, machines, features, and clients, and enforce that separation through types and checks. Use when asked to simplify, review, or replace a design, "what would Rich Hickey do", "optimize for deletion", or "define this error out of existence". → [Read page](https://ratstack.sh/skills/uncomplect)
