Skip to content
UNDERSTUDY(3)rasuvaeff PHP Library ManualUNDERSTUDY(3)

NAME ​

understudy — test doubles where the configured call is a real method call, not a method-name string

SYNOPSIS ​

$ 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.

DESCRIPTION ​

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.

  • Specifies calls as real closures: when(fn () => $repo->find(123))->returns($book).
  • expect() with times(); after-the-fact verify() (including never: true) and nothingElse().
  • Argument matchers: Arg::any, satisfies, rest, and a captor with typed last() / all().
  • Doubles several interfaces at once; handles final classes and PHP 8.4 property hooks.
  • Understudy::delegate() forwards unstubbed calls to a real object and records them.
  • One context per fiber instead of shared static state.
  • #[\SensitiveParameter] arguments are redacted in failure messages and transcript().

EXAMPLES ​

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

SEE ALSO ​

PackageRole
understudy-testo(3)Testo adapter
understudy-phpunit(3)PHPUnit and Pest adapter
understudy-psalm(3)Psalm plugin
understudy-phpstan(3)PHPStan extension

BUGS ​

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.

DEPENDENCIES

required by: understudy-phpstan(3), understudy-phpunit(3), understudy-psalm(3), understudy-testo(3)

HISTORY

First released as v0.1.0 on 2026-08-25; 21 releases in all.

v1.1.12026-10-14
v1.1.02026-10-13
v1.0.12026-10-08
v1.0.02026-09-27
v0.12.02026-09-19
v0.11.02026-09-18
v0.10.02026-09-06
v0.9.02026-09-05
v0.8.02026-09-05
v0.7.22026-09-04

… and 11 earlier. All releases

rasuvaeff/understudy 1.1.1mutation gate 92%used by 4 packagesUNDERSTUDY(3)

/ search · n N next, previous · g G top, bottom · q back to the index