---
name: Brain\Monkey testing patterns
description: Specific Brain\Monkey 2.x API quirks that caused test failures — use these patterns to avoid repeating mistakes
type: feedback
---

Use `Functions\when('fn')->alias(fn() => ...)` for closure-based stubs. NOT `returnUsing()` (doesn't exist).

**Why:** Discovered during initial test scaffold — `returnUsing()` throws "Call to undefined method".

**How to apply:** Any time a WP function needs to return different values based on arguments (e.g. `get_role` returning different values per role), use `Functions\when()->alias()`.

---

Use `Functions\when()` instead of `Functions\expect()` when routing by argument.

**Why:** Chaining two `Functions\expect('get_role')->with(A)` / `Functions\expect('get_role')->with(B)` caused the second expectation to silently override the first rather than adding an alternative route, leading to unexpected "0 calls" failures.

**How to apply:** When a function needs to return different values for different args, use `Functions\when()->alias(fn($arg) => match($arg) { ... })`. Use `Functions\expect()` only when asserting call count/args.

---

Mockery matchers don't work inside plain PHP arrays in `with()`.

**Why:** `->with('init', [\Mockery::type(Foo::class), 'method'])` never matched because Mockery can't evaluate matchers nested in arrays this way.

**How to apply:** Use `\Mockery::any()` or `\Mockery::on(fn($arr) => ...)` for the entire array argument instead.

---

`TestCase::setUp()` must call `Monkey\Functions\stubTranslationFunctions()` and `Monkey\Functions\stubEscapeFunctions()`.

**Why:** WP i18n functions (`__`, `_e`, etc.) are not auto-stubbed — they don't exist in the test environment. Without explicit stubs, PHP throws "Call to undefined function" as soon as any WP code path hits `__()`.

**How to apply:** Already done in `tests/Unit/TestCase.php`. Don't remove these calls.