fusengine/php-testing

PHP Testing

Two frameworks, one engine. Pest is a layer over PHPUnit — both need PHP 8.3+ and share the same runner and assertions underneath.

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

1. fuse-ai-pilot:explore-codebase - Detect existing framework (phpunit.xml vs Pest.php), test layout, PHP version
2. fuse-ai-pilot:research-expert - Verify latest PHPUnit 12 / Pest 4 docs via Context7/Exa
3. mcp__context7__query-docs - Check attribute names, test-double API, config schema

After implementation, run fuse-ai-pilot:sniper for validation.

---

Overview

| Framework | Style | Strength | |-----------|-------|----------| | PHPUnit 12 | Class-based, xUnit | Enterprise baseline, explicit, widest tooling/CI support | | Pest 4 | Closure-based, expressive | Modern DX, browser + arch + mutation testing, less boilerplate |

Pest 4 runs on PHPUnit's engine, so PHPUnit knowledge transfers directly. The choice is about ergonomics and team preference, not capability.

---

Critical Rules

1. PHP 8.3+ required - Both PHPUnit 12 and Pest 4 drop older PHP
2. Attributes only, no annotations - PHPUnit 12 removed docblock annotations (@test, @dataProvider)
3. Data providers are public static - Non-static providers no longer work
4. createStub() is not configurable - Configure expectations only on createMock()
5. One framework per project - Pest or PHPUnit, not both driving the same suite
6. Mock at boundaries - Network/DB/clock, never internal implementation detail

---

Decision Guide

Choosing a framework? (non-Laravel)
├── Enterprise / strict CI / mixed team → PHPUnit 12 (explicit, ubiquitous)
├── Modern DX, greenfield, small team → Pest 4 (concise, expressive)
├── Need browser / architecture / mutation testing out of the box → Pest 4
└── Migrating a large PHPUnit suite → stay PHPUnit, or drift-migrate to Pest

Honest note: PHPUnit is the enterprise/CI baseline; Pest has strong community momentum but that trend is not normative. Either is a correct, well-supported choice — pick per team, not per hype.

→ Full matrix in references/choosing-framework.md

---

Reference Guide

Concepts

| Topic | Reference | Load when | |-------|-----------|-----------| | Framework choice | references/choosing-framework.md | Deciding PHPUnit vs Pest | | PHPUnit 12 | references/phpunit-12.md | Writing PHPUnit tests | | Pest 4 | references/pest-4.md | Writing Pest tests | | Annotation migration | references/annotations-to-attributes.md | Upgrading pre-12 tests |

Templates

| Template | Use Case | |----------|----------| | references/templates/phpunit-xml.md | phpunit.xml + first TestCase | | references/templates/pest-setup.md | Pest.php + first Pest tests | | references/templates/test-doubles.md | Stubs, mocks, fixtures, coverage |

---

Quick Start

PHPUnit 12

use PHPUnit\Framework\TestCase;

final class GreeterTest extends TestCase
{
    public function testGreets(): void
    {
        $this->assertSame('Hi, Al', (new Greeter)->greet('Al'));
    }
}

Pest 4

it('greets', function () {
    expect((new Greeter)->greet('Al'))->toBe('Hi, Al');
});

---

Best Practices

DO

• Name tests by behavior (testRejectsExpiredToken), assert one behavior each
• Use #[DataProvider] with public static providers for table-driven tests
• Gate CI on an explicit coverage threshold, not a report

DON'T

• Keep @test / @dataProvider annotations (removed in PHPUnit 12)
• Configure expectations on createStub() results
• Mock the class under test — mock its collaborators