understudy — test doubles where the configured call is a real method call, not a method-name string
$ composer require --dev rasuvaeff/understudy
use Rasuvaeff\Understudy\Understudy;use function Rasuvaeff\Understudy\expect;use function Rasuvaeff\Understudy\when; $repository = Understudy::for(BookRepository::class); when(fn () => $repository->find(123))->returns($book); expect(fn () => $repository->save($book))->times(1);
Rename find and the IDE renames the call with it; a stale call is flagged by static analysis. for() returns the contract's own type.
Test doubles where the configured call is a real call, not a method-name string.
String-based mocks break on refactoring and typos, and they add service methods (shouldReceive, expects) to the double that the doubled contract can then never use.
when(fn () => $repo->find(123))->returns($book).expect() with times(); after-the-fact verify() (including never: true) and nothingElse().Arg::any, satisfies, rest, and a captor with typed last() / all().Understudy::delegate() forwards unstubbed calls to a real object and records them.#[\SensitiveParameter] arguments are redacted in failure messages and transcript().A typed argument captor reads what the code under test actually passed, with no instanceof checks.
$options = Arg::captor(DeliveryOptions::class); // Captor<DeliveryOptions>when(fn () => $store->temporaryUrl(Arg::any(), Arg::any(), $options->capture())) ->returns('https://…'); $subject->run(); $options->last()->downloadName; // typed: DeliveryOptions$options->all(); // list<DeliveryOptions>, in call order
A where() guard constrains several arguments together; calls it rejects fall back to the default answer.
$ledger = Understudy::for(Ledger::class);Understudy::label($ledger, 'ledger'); when(fn() => $ledger->transfer(Arg::any(), Arg::any())) ->where(fn(int $from, int $to) => $from <= $to, description: 'where(from <= to)') ->returns(true); $ledger->transfer(3, 7); // true: the where() guard accepts it$ledger->transfer(9, 4); // false: refused by the guard, falls to the default answer
Strict mode refuses any call nobody described, and the refusal names that call.
$strict = Understudy::for(Clock::class);Understudy::label($strict, 'clock');Understudy::strict($strict); when(fn() => $strict->now())->returns(7); try { $strict->zone();} catch (StrictModeViolation $violation) { $violation->getMessage();names the refused call: zone()}
| Package | Role |
|---|---|
| understudy-testo(3) | Testo adapter |
| understudy-phpunit(3) | PHPUnit and Pest adapter |
| understudy-psalm(3) | Psalm plugin |
| understudy-phpstan(3) | PHPStan extension |
A when() is permission, not a claim. expect() counts only calls matching its own arguments, so add Understudy::nothingElse() to catch other calls. Dev dependency only, not for production.
Requires PHP 8.3–8.5 and ext-tokenizer.
required by: understudy-phpstan(3), understudy-phpunit(3), understudy-psalm(3), understudy-testo(3)
First released as v0.1.0 on 2026-08-25; 21 releases in all.
| v1.1.1 | 2026-10-14 |
| v1.1.0 | 2026-10-13 |
| v1.0.1 | 2026-10-08 |
| v1.0.0 | 2026-09-27 |
| v0.12.0 | 2026-09-19 |
| v0.11.0 | 2026-09-18 |
| v0.10.0 | 2026-09-06 |
| v0.9.0 | 2026-09-05 |
| v0.8.0 | 2026-09-05 |
| v0.7.2 | 2026-09-04 |
… and 11 earlier. All releases
/ search · n N next, previous · g G top, bottom · q back to the index