> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-testing/property-based-tests.md). # Property-based tests A traditional test is a pair: this input, that output. A person picks five or ten examples based on how they understand the implementation, and asserts what should come back. Generated code is stochastic. The same prompt produces a different implementation on a different day. It may handle the ten hand-picked examples perfectly and quietly mishandle the millions nobody wrote down. Testing code that varies with examples that do not is a mismatch at the root. Property-based testing closes that gap. Instead of naming individual cases, you declare a **property**: something that must hold for every valid input. The framework then generates hundreds or thousands of inputs and tries to break it. When it finds a counterexample, it shrinks it to the smallest version that still fails, so what lands in front of you is the essence of the bug rather than a random one. ## Three patterns worth knowing **Invariants.** Something that is true regardless of the values: a total is never negative, a balance never exceeds a limit, a sorted list stays sorted. **Oracles.** A second, obviously correct implementation to compare against: a slow reference version, a previous release, an off-the-shelf library. **Round trips.** Encode then decode, serialise then parse, write then read. Whatever comes back must equal what went in. ## What it is worth In a like-for-like comparison on a pricing module, a hand-written suite reached ninety per cent line coverage, a seventy-three per cent mutation score, and found neither of the two real bugs. A property-based suite with lower coverage found both: an early rounding of the discount rate, and the wrong rounding mode on VAT. By every metric a dashboard shows, the traditional suite looked better. The bugs disagreed. That is the reason this layer exists, and the reason coverage is a poor stopping rule. ## Where it fits Properties are worth writing where the input space is large and the rules are stateable: money, dates, parsers, permissions, anything with arithmetic or ordering. They are not a replacement for examples. A named example still documents intent better than any generator, and a regression deserves its own test with a name. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.visdom.virtuslab.com/visdom-testing/property-based-tests.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.