Download the PHP package rasuvaeff/property-testing-phpunit without Composer

rasuvaeff/property-testing-phpunit

Русская версия

PHPUnit adapter for the property-testing engine: a PropertyTesting trait with a fluent forAll()->check() API over the framework-agnostic runner. Generate hundreds of random inputs per test, find the failing one, and shrink it to a minimal counterexample you can actually read — inside an ordinary PHPUnit TestCase.

Using an AI coding assistant? llms.txt contains a compact API reference you can share with the model.

Part of the property-testing family

Requirements

• PHP 8.3+
• phpunit/phpunit ^11.5 || ^12.0 || ^13.0
• rasuvaeff/property-testing-core ^0.9 || ^0.10

PHPUnit 13 requires PHP 8.4.1 or newer. On PHP 8.3, Composer resolves a compatible PHPUnit 11 or 12 release.

Installation

No configuration is needed: mix the trait into a TestCase and call forAll() from a test method.

Usage

Map each property-body parameter to a generator, configure the run with the fluent chain, and hand the property to check(). The engine generates random arguments, runs the closure the configured number of times, and on the first failure shrinks the counterexample to a minimal one:

The closure's parameter names select the generators, exactly like a #[Property] method signature does under the Testo adapter. On failure the test fails with the engine's message:

Reproduce the exact run by pinning the reported seed: ->seed(7382910).

The fluent chain

forAll() returns a PropertyCheck; every setter returns it for chaining, and check() runs the property.

Auto-derived generators (auto())

When the closure's parameters are fully described by their types, the forAll() map can go away entirely: auto() derives a generator for every uncovered parameter from the closure's own signature via Gen::forParameters() — the @param psalm type when the closure carries a docblock (int<1, 300>, non-empty-string, list<T>, 'a'|'b'), the native type otherwise. A docblock over a closure is legal PHP, and reflection sees it in every natural placement:

The forAll() map becomes the overrides and may be partial — the escape hatch for domains no psalm type can express (a float range, a dependent pair built with Gen::flatMap()):

Rules worth knowing — verbatim the Testo adapter's (#[Property(auto: true)]):

• Strictly opt-in. A bare int or float derives its full native domain, and only the property's author knows whether that is the intended one. Annotate or override anything narrower.
• A type the deriver cannot read (a bare array, mixed, an untyped or variadic parameter) fails with an error naming the function and the parameter — never a silently widened guess.
• With auto() a forAll() key that is not a parameter of the closure is an error: merge semantics would otherwise silently replace a typoed entry with a signature-derived generator.
• A full map plus auto() is legal — auto derives nothing.
• There is deliberately no PROPERTY_AUTO environment variable: the environment dials the suite, while auto() changes what one property's arguments mean.

Naming a property (id())

id() names the property:

Left out, the name is derived from the calling method — which is right for a test method and wrong for a closure, because PHP has no stable name for one. On PHP 8.3 every closure of a class is {closure}, so two properties in one file share a corpus key and overwrite each other's recorded counterexample; from 8.4 the name is {closure:/path/File.php:19}, so inserting a line above the property orphans yesterday's entry. Nothing throws — the corpus just stops replaying the failure it exists to replay.

So call id() whenever forAll() runs inside a closure rather than directly in a test method (Pest's it() and test() are the common case). The id keys the regression corpus and every event, and it also becomes the display name, so one string identifies the property in the corpus, in the events and in the printed output.

Expected exceptions (throws())

expectException() cannot work inside a check() closure: the executor observes every throw before PHPUnit's own expectation mechanism does, so the expected exception would falsify the property. throws() states the expectation where it is checked:

Semantics, per trial:

• Throws the class (a subclass matches) — the trial passes.
• Returns normally — the trial fails with Expected <class> to be thrown, but it was not, and the input shrinks like any other counterexample.
• Throws another class — that throw is the failure, exactly as it would be without throws().
• markTestSkipped()/markTestIncomplete() still skip the run, and an Assume::that() discard still discards it: the environment's verdict about the run is never a pass earned by throwing.

A class that is not a Throwable is rejected immediately — a typoed name would otherwise falsify every run without a word of explanation.

How results map onto PHPUnit

• A pass counts one assertion — the test is never marked risky.
• Every failing outcome (falsified, gave up, unmet coverage, deadline, budget, generation failure, failing example, replayed regression) surfaces as one AssertionFailedError whose message is the engine's own — seed, original and shrunk arguments, shrink statistics — and whose previous is the engine exception (PropertyViolationException, GaveUpException, RegressionViolationException, …).
• Assume::that() is a discarded run inside the property, retried by the engine — never a skipped PHPUnit test.
• markTestSkipped() / markTestIncomplete() inside the body skip that run (a discard); when every run skipped, the skip is rethrown and PHPUnit reports the test as skipped or incomplete. Partly skipped runs spend a budget of their own, separate from maxDiscards: since core 0.9 a skip is not a discard, and when that budget runs out the message names the environment rather than advising narrower generators. Unlike an Assume::that() discard, a skip says nothing about the input, so a recorded regression whose replay only skipped stays in the corpus instead of being pruned.
• expectException() does not see the body's exception: the engine catches it as the run's failure. Declare the expectation with throws() instead, or assert on the exception inside the body.
• setUp() runs once per test, not per generated input — a property is one test method with one check().
• With a data provider, the corpus id carries the data set name (Class::method with data set "large"), so the sets do not replay — and prune — each other's regressions. The unstable-id warning is printed only when a corpus is in use, once per id.

Environment overrides

Byte-for-byte parity with the Testo adapter — one contract across adapters:

PROPERTY_DB takes either a directory or a Redis DSN:

The DSN has the shape everything else gives it (the IANA registration, predis, Symfony): the path is the database index, the key prefix is the prefix query parameter, rediss:// is TLS. The pre-0.6 form with the prefix in the path (redis://host/suite-a:) is refused with the new spelling in the message. The value is parsed by the engine's CorpusFactory, shared with the Testo adapter.

A directory remembers a counterexample for whoever owns it — in CI, a machine deleted when the job ends. The Redis form is the same corpus, in the same document, shared. It needs ext-redis or predis/predis; neither installed is an error rather than a silent fall back to the filesystem. A PROPERTY_DB with any other scheme — a rediss:// typo, another backend — is likewise an error, never a directory named after the scheme. Credentials in the DSN (redis://user:pass@host) are rejected rather than silently dropped; configure Redis AUTH out of band.

The corpus format is exactly the one rasuvaeff/property-testing 2.8 wrote — a corpus recorded under Testo (or under 2.x) replays here and vice versa. On falsification the minimal input is recorded; the next run replays recorded failures first (unless seed() pins the property) and reports a still-red one as a RegressionViolationException; a green one is pruned.

Distribution and discards

Classify::label()/when()/cover() work inside the property body. When a classified property passes, the adapter prints the label distribution:

A property that discards more than 90% of its attempts (via Assume::that()) gets a warning suggesting narrower generators.

Why no #[Property] attribute?

PHPUnit's public extension/event API observes test execution but offers no stable contract for intercepting and re-invoking a test method many times — which is exactly what a property attribute must do. This adapter deliberately does not depend on PHPUnit internals; the fluent API needs only the documented surface. An attribute may appear later, only if it can be built on the documented extension API of the supported majors.

Generators

The full generator catalog (Gen::int() … Gen::subset(), Gen::regex(), Gen::commands(), Gen::draw(), Shrinkable, writing your own ArbitraryInterface, stateful/model-based testing) is the engine's API, documented in the core README. Everything there is usable from a check() closure as-is.

Public API of this package

VerboseListener, PhpUnitTrialExecutor, the PropertyCheck constructor and its output() seam are @internal. The environment variables and the PROPERTY_DB DSN are parsed by the engine (EnvironmentOverrides, CorpusFactory), so they mean the same thing under the Testo adapter.

Security

Generated values are pseudo-random (seeded MT19937), not cryptographic. Seeds are not secrets — they are printed in failure output by design. Treat PROPERTY_DB corpus files as test artifacts: they contain generated inputs verbatim, so do not point the variable at a directory that gets published.

Examples

See examples/ — a complete property-based TestCase:

Development

Tests run through PHPUnit (composer test is phpunit), not Testo.

License

BSD-3-Clause