FilesystemCorpus

Rasuvaeff\PropertyTesting\Runner\FilesystemCorpus

Class — Package: property-testing-core — Source — Version: v0.1.0-12-g86ead85

Implements: Runner\Corpus

Opt-in on-disk corpus of a property's past failures, replayed before the random phase so a fixed bug stays fixed (fast regression replay).

A failure is recorded as its minimised input whenever Internal\ValueCodec can represent every argument as data — such an entry replays as a single run and survives changes to the generation sequence. Inputs that cannot be represented (objects, closures, in-body Gen::draw() pseudo-arguments) fall back to storing the run's seed, which reproduces the failure only while the generation sequence is unchanged; Runner\SEQUENCE_EPOCH fences those entries off when it is not.

Enabled solely when the PROPERTY_DB environment variable points at a directory; otherwise storage is off and nothing is written. One file per property (<sha1(id)>.json) keeps it gitignore-friendly.

Constants

Constant	Type	Value	Description
FORMAT_VERSION	int	1	On-disk layout version. A file written by a different version is ignored wholesale rather than guessed at.
SEQUENCE_EPOCH	int	1	Generation-sequence epoch. Seed entries reproduce a failure only while the seed→values mapping holds, so bump this in any release that shifts the generated sequence (new boundary bias, changed draw order, a rewritten arbitrary) — older seed entries are then dropped instead of replaying a different input under the guise of a regression. Values entries carry the input itself and are unaffected.

Constructor

__construct(
    string $directory,
)

Parameter	Type	Default	Description
$directory	string	required

Methods

fromEnv()

static fromEnv(): ?self

The storage configured by PROPERTY_DB (a directory path), or null when the variable is unset/empty (storage disabled — no files are written).

recall()

recall(string $id, list<string> $parameterNames): array

The usable entries recorded for $id, cheapest first (values before seeds, most recently recorded first within each kind).

• $parameterNames — The property method's current parameters, in order.

Unusable entries are silently skipped: a corrupt file, a foreign format version, a value the codec can no longer decode (renamed enum), a seed from a superseded Runner\SEQUENCE_EPOCH, or a values entry whose argument names no longer match $parameterNames (the property's signature changed, so replaying it would feed the body a different input).

remember()

remember(
    string $id,
    CounterExample $counterExample,
    list<string> $parameterNames,
): void

Records $counterExample as the newest entry for $id, preferring its minimised arguments over the bare seed.

• $parameterNames — The property method's current parameters, in order.

prune()

prune(string $id, Runner\CorpusEntry $entry): void

Drops $entry from $id's corpus — the replay no longer fails, so the regression is fixed and the entry has served its purpose.