Test Data Builders
debt(d7/e5/b3/t5)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints indicate automated detection is 'no' and the tools listed (phpunit, pest) are test runners, not static analysers that flag missing builders. The code pattern — large factory calls, copy-pasted setup, unclear relevance — is only visible through code review. No linter or SAST rule reliably flags the absence of the builder pattern.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix describes creating a builder class per domain object, but the common_mistakes reveal multiple layers: adding sensible defaults, renaming methods semantically, refactoring test setup across test files. This is not a single-line swap — it involves introducing new builder classes and touching every test that currently uses raw factory calls or large parameter arrays.
Closest to 'localised tax' (b3). The choice applies within the test suite only (applies_to covers web/cli/queue but the pattern itself is test-scoped). Once builders are in place they carry some maintenance overhead (keeping builders in sync with domain objects), but the rest of the production codebase is unaffected. The tax is real but contained to the testing layer.
Closest to 'notable trap — a documented gotcha most devs eventually learn' (t5). The misconception field explicitly states that developers confuse test data builders with Laravel/Faker factories, believing factories serve the same purpose. This is a well-documented confusion in the PHP/Laravel ecosystem: factories generate randomised realistic data while builders provide controlled, semantically meaningful data for specific test scenarios. The common_mistakes (no defaults, shared state, non-semantic naming) reinforce that misuse is common before the pattern is properly understood.
Also Known As
TL;DR
Explanation
The Object Mother pattern provides pre-built test objects; the Builder pattern gives fine-grained control. A test data builder creates an object with safe defaults and exposes named override methods: UserBuilder::create()->withEmail('test@example.com')->asAdmin()->build(). Only the fields relevant to the test need to be specified — all others use defaults. This keeps tests focused on the behaviour under test rather than construction boilerplate.
Common Misconception
Why It Matters
Common Mistakes
- Not giving the builder sensible defaults — every test having to specify every field defeats the purpose.
- Using the same builder object across multiple tests without resetting state — builders should create fresh objects each time.
- Not naming builder methods semantically: withAdminRole() is clearer than withRole('admin').
- Building complex graphs of related objects inside assertions rather than in setup — obscures what is being tested.
Code Examples
// Test setup noise obscures what is being tested:
public function testAdminCanDeleteUser(): void {
$admin = new User();
$admin->id = 1;
$admin->name = 'Admin'; // Irrelevant
$admin->email = 'a@example.com'; // Irrelevant
$admin->createdAt = new DateTime(); // Irrelevant
$admin->role = 'admin'; // This is the relevant part
// ... 10 more irrelevant fields
}// Builder — only relevant data specified:
public function testAdminCanDeleteUser(): void {
$admin = UserBuilder::create()->asAdmin()->build();
$user = UserBuilder::create()->build();
$this->assertTrue($admin->canDelete($user));
$this->assertFalse($user->canDelete($admin));
}