Claude Skill

phpunit

PHPUnit testing framework conventions and practices. Invoke whenever task involves any interaction with PHPUnit — writing tests, configuring PHPUnit, data providers, mocking, assertions, debugging test failures, or coverage.

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download xobotyi-cc-foundry-plugins_php_skills_phpunit-278c16c.zip · 13 KB

Install

skills CLI npx skills add https://github.com/xobotyi/cc-foundry/tree/master/plugins/php/skills/phpunit
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install xobotyi-cc-foundry@llmmart
Git git clone https://github.com/xobotyi/cc-foundry.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole xobotyi/cc-foundry collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

PHPUnit

Test behavior, not implementation. Tests are executable documentation — if the test name doesn't explain what the code does, rewrite it.

PHPUnit is PHP's standard testing framework. It uses test case classes extending TestCase, setUp()/tearDown() for fixtures, and a full assertion API. All patterns target PHPUnit 11+ on PHP 8.5+. Use PHP 8 attributes exclusively — annotations are deprecated in 11, removed in 12.

References

  • Assertion catalog, constraints, exception expectations → [${CLAUDE_SKILL_DIR}/references/assertions.md] — Full assertion API grouped by category, constraint system, custom assertions
  • Test doubles — stubs, mocks, MockBuilder → [${CLAUDE_SKILL_DIR}/references/mocking.md] — createStub vs createMock, return config, invocation matchers, argument constraints, MockBuilder
  • Data providers — static, named, generators → [${CLAUDE_SKILL_DIR}/references/data-providers.md] — #[DataProvider], #[TestWith], named datasets, generator providers, external providers
  • phpunit.xml structure, test suites, source config → [${CLAUDE_SKILL_DIR}/references/configuration.md] — XML elements, strict settings, source element, coverage reports, execution order

Test Structure

Discovery and Naming

  • Files: *Test.php in configured test directories. Mirror source structure: src/Service/PaymentService.php → tests/Unit/Service/PaymentServiceTest.php.
  • Classes: final class PaymentServiceTest extends TestCase. Always final.
  • Methods: test prefix or #[Test] attribute. Describe the behavior: testReturnsEmptyCollectionWhenNoResults not testSearch.
  • One test class per production class. Split into Unit/Integration directories.

Arrange-Act-Assert

Structure every test in three phases:

public function testUserCreationSetsDefaults(): void
{
    // Arrange
    $data = ['name' => 'Alice', 'email' => 'alice@example.com'];

    // Act
    $user = User::fromArray($data);

    // Assert
    $this->assertSame('Alice', $user->getName());
    $this->assertTrue($user->isActive());
    $this->assertSame([], $user->getRoles());
}
  • One act per test. If you need multiple acts, write multiple tests.
  • Comments optional when phases are obvious. Add them when the test is long enough that phases aren't immediately clear.

Test Granularity

  • One concept per test. Multiple assertions are fine when they verify the same behavior. Separate tests when behaviors are independent.
  • Fast by default. Unit tests should run in milliseconds. Gate slow tests behind groups: #[Group('slow')].
  • Isolation is mandatory. Tests must not depend on execution order or shared mutable state. Each test sets up its own world.

Fixtures

setUp() / tearDown()

  • setUp() runs before each test method on a fresh instance. Create the SUT and its stubs here.
  • tearDown() runs after each test. Only needed for external resources (files, sockets, DB connections). Not needed for plain object cleanup.
  • setUpBeforeClass() / tearDownAfterClass() run once per class. Use for expensive shared resources (DB connections). Store in static properties.
final class PaymentServiceTest extends TestCase
{
    private PaymentService $service;
    private Gateway&Stub $gateway;

    protected function setUp(): void
    {
        $this->gateway = $this->createStub(Gateway::class);
        $this->service = new PaymentService($this->gateway);
    }
}

Fixture Lifecycle

  • setUpBeforeClass() — Class scope; once before first test
  • setUp() — Method scope; before each test
  • assertPreConditions() — Method scope; after setUp, before test
  • assertPostConditions() — Method scope; after test, before tearDown
  • tearDown() — Method scope; after each test
  • tearDownAfterClass() — Class scope; once after last test
  • Call parent::setUp() when extending abstract test cases — otherwise parent fixture setup is silently skipped.
  • Use #[Before] / #[After] attributes when multiple setup methods are needed (avoids fragile parent::setUp() chains).

Data Providers

Basic Usage

use PHPUnit\Framework\Attributes\DataProvider;

#[DataProvider('additionCases')]
public function testAdd(int $a, int $b, int $expected): void
{
    $this->assertSame($expected, $a + $b);
}

public static function additionCases(): array
{
    return [
        'zeros'        => [0, 0, 0],
        'positive sum' => [1, 2, 3],
        'negative'     => [-1, 1, 0],
    ];
}
  • Providers must be public static. Non-static providers are removed in PHPUnit 11.
  • Always use named datasets — string keys produce readable failure output.
  • Use #[DataProvider] attribute, not @dataProvider annotation.

Inline Data

For small, simple datasets — no provider method needed:

use PHPUnit\Framework\Attributes\TestWith;

#[TestWith([0, 0, 0])]
#[TestWith([1, 2, 3])]
#[TestWith([-1, 1, 0])]
public function testAdd(int $a, int $b, int $expected): void
{
    $this->assertSame($expected, $a + $b);
}

Generator Providers

For large or computed datasets:

public static function boundaryCases(): Generator
{
    yield 'min int' => [PHP_INT_MIN, 0, PHP_INT_MIN];
    yield 'max int' => [PHP_INT_MAX, 0, PHP_INT_MAX];
}

Provider Rules

  • Data must be scalar or immutable — no service objects or complex graphs in providers.
  • No mock objects in providers — framework isn't initialized during provider execution.
  • Empty providers are forbidden in PHPUnit 11 — throws InvalidDataProviderException.
  • Multiple providers can be stacked on one test method — datasets are combined.

See ${CLAUDE_SKILL_DIR}/references/data-providers.md for external providers, TestDox integration, and edge cases.

Assertions

Core Assertions

$this->assertSame($expected, $actual);        // Strict === (preferred)
$this->assertEquals($expected, $actual);       // Loose == (use sparingly)
$this->assertTrue($condition);
$this->assertFalse($condition);
$this->assertNull($value);
$this->assertInstanceOf(Expected::class, $obj);
$this->assertCount(3, $collection);
$this->assertEmpty($collection);
$this->assertArrayHasKey('key', $array);
$this->assertContains($needle, $haystack);     // Strict comparison
  • Prefer assertSame() over assertEquals() — strict type comparison catches more bugs.
  • Multiple assertions per test are fine when they verify the same behavior.

String Assertions

$this->assertStringStartsWith('Error:', $message);
$this->assertStringEndsWith('.php', $filename);
$this->assertStringContainsString('needle', $haystack);
$this->assertMatchesRegularExpression('/^\d{4}-\d{2}$/', $date);

Float Comparison

$this->assertEqualsWithDelta(3.14, $result, 0.01);

Exception Testing

public function testThrowsOnInvalidInput(): void
{
    $this->expectException(InvalidArgumentException::class);
    $this->expectExceptionMessage('must be positive');

    $calculator->divide(1, 0);
}
  • Call expectException() before the throwing code — it sets up the expectation.
  • Use expectExceptionMessage() when the exception type is broad — validates the message contains the substring.
  • Use expectExceptionMessageMatches() for regex matching.

Deprecation / Error Expectations

public function testTriggersDeprecation(): void
{
    $this->expectUserDeprecationMessage('use newMethod() instead');

    $service->oldMethod();
}

See ${CLAUDE_SKILL_DIR}/references/assertions.md for the full assertion catalog, constraint system, and format string assertions.

Mocking

Stubs vs Mocks

  • Stub (createStub()) — controls return values. No call verification.
  • Mock (createMock()) — verifies interactions (method called, arguments matched).

Use stubs by default. Use mocks only when verifying that a side effect occurred.

Creating Stubs

$repo = $this->createStub(UserRepository::class);
$repo->method('find')->willReturn(new User(name: 'Alice'));

$service = new UserService($repo);
$result = $service->getUser(1);

$this->assertSame('Alice', $result->name);

Shorthand for multiple methods:

$repo = $this->createConfiguredStub(UserRepository::class, [
    'find'   => new User(name: 'Alice'),
    'exists' => true,
]);

Creating Mocks

$logger = $this->createMock(Logger::class);
$logger->expects($this->once())
    ->method('error')
    ->with($this->stringContains('payment failed'));

$service = new PaymentService($logger);
$service->process($invalidPayment);

Return Value Configuration

$stub->method('fetch')->willReturn('value');              // Fixed value
$stub->method('fetch')->willReturn('a', 'b', 'c');       // Consecutive values
$stub->method('fetch')->willReturnArgument(0);            // Return first arg
$stub->method('fetch')->willReturnSelf();                 // Fluent interface
$stub->method('fetch')->willReturnCallback(fn ($id) => "item-{$id}");
$stub->method('fetch')->willThrowException(new RuntimeException('fail'));
$stub->method('fetch')->willReturnMap([
    ['key1', 'value1'],
    ['key2', 'value2'],
]);

Mocking Rules

  • Mock at boundaries. Mock external services, databases, filesystems, clocks — not internal functions.
  • Don't mock what you own when a fake or in-memory implementation is available.
  • Prefer dependency injection over complex mock setup. Pass collaborators as constructor parameters, stub in tests.
  • Never mock the thing you're testing. If you need to mock part of the SUT, the SUT has too many responsibilities — split it.
  • Favour interfaces over classes for test doubles — fewer limitations, better design.
  • Do not call expects() on stubs — deprecated in 11, error in 12.

See ${CLAUDE_SKILL_DIR}/references/mocking.md for MockBuilder, intersection types, invocation matchers, and PHP 8.4 property hooks.

Attributes

PHPUnit 11 uses PHP 8 attributes exclusively. All attributes are in the PHPUnit\Framework\Attributes namespace.

Test Metadata

  • #[Test] — Mark non-test* method as a test
  • #[DataProvider('method')] — Connect a data provider
  • #[DataProviderExternal(Class::class, 'method')] — External data provider
  • #[TestWith([args])] — Inline data provider
  • #[TestDox('description')] — Custom TestDox description
  • #[Depends('testMethod')] — Declare test dependency
  • #[Group('name')] — Assign to group
  • #[Ticket('PROJ-123')] — Link to issue tracker

Skip / Conditional

  • #[RequiresPhp('>= 8.4')] — Skip if PHP version doesn't match
  • #[RequiresPhpExtension('pdo_pgsql')] — Skip if extension missing
  • #[RequiresOperatingSystemFamily('Linux')] — Skip on other OS
  • #[RequiresFunction('sodium_crypto_sign')] — Skip if function missing
  • #[RequiresMethod(PDO::class, 'sqliteCreateFunction')] — Skip if method missing

Coverage

  • #[CoversClass(ClassName::class)] — Test covers this class
  • #[CoversFunction('functionName')] — Test covers this function
  • #[CoversMethod(ClassName::class, 'method')] — Test covers this method
  • #[CoversNothing] — Test contributes no coverage (integration tests)
  • #[UsesClass(ClassName::class)] — Allowed but not covered dependency
  • #[UsesFunction('functionName')] — Allowed but not covered function

Fixture

  • #[Before] — Run method before each test (alternative to setUp)
  • #[After] — Run method after each test (alternative to tearDown)
  • #[BeforeClass] — Run static method before first test
  • #[AfterClass] — Run static method after last test
  • #[BackupGlobals(true)] — Backup/restore globals for this test
  • #[BackupStaticProperties(true)] — Backup/restore static properties

Test Behavior

  • #[DoesNotPerformAssertions] — Suppress risky test warning
  • #[RunInSeparateProcess] — Isolate in separate PHP process
  • #[RunTestsInSeparateProcesses] — All tests in class run isolated
  • #[Small] / #[Medium] / #[Large] — Time limit enforcement (1s/10s/60s)

Test Organization

Directory Structure

tests/
├── Unit/                     # Fast, isolated, no I/O
│   ├── Service/
│   │   └── PaymentServiceTest.php
│   └── Model/
│       └── UserTest.php
├── Integration/              # Real dependencies, slower
│   └── Repository/
│       └── UserRepositoryTest.php
└── bootstrap.php             # Autoloader for tests
  • Mirror source directory structure under tests/Unit/ and tests/Integration/.
  • Unit tests — no database, no filesystem, no network. Mock all boundaries.
  • Integration tests — real dependencies. Mark with #[CoversNothing] to avoid polluting coverage metrics.

Test Suites

Define in phpunit.xml for selective execution:

<testsuites>
    <testsuite name="unit">
        <directory>tests/Unit</directory>
    </testsuite>
    <testsuite name="integration">
        <directory>tests/Integration</directory>
    </testsuite>
</testsuites>

Run subsets: phpunit --testsuite unit, phpunit --group slow.

Configuration

Recommended phpunit.xml

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.5/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true"
         cacheDirectory=".phpunit.cache"
         executionOrder="depends,random"
         beStrictAboutTestsThatDoNotTestAnything="true"
         beStrictAboutOutputDuringTests="true"
         failOnWarning="true"
         failOnRisky="true"
         failOnDeprecation="true"
         failOnNotice="true">
    <testsuites>
        <testsuite name="unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="integration">
            <directory>tests/Integration</directory>
        </testsuite>
    </testsuites>
    <source restrictDeprecations="true"
            restrictNotices="true"
            restrictWarnings="true">
        <include>
            <directory suffix=".php">src</directory>
        </include>
    </source>
</phpunit>

Key Configuration Choices

  • executionOrder="depends,random" — randomize test order to catch hidden dependencies while respecting explicit #[Depends].
  • beStrictAboutTestsThatDoNotTestAnything="true" — flag tests without assertions as risky.
  • failOnDeprecation="true" — catch deprecations from your code early.
  • <source> with restrictDeprecations — only surface issues from your code, not vendor dependencies.
  • cacheDirectory — add .phpunit.cache to .gitignore.

Code Coverage

Requires PCOV or Xdebug extension:

phpunit --coverage-html build/coverage --coverage-clover build/clover.xml

Use #[CoversClass] and #[UsesClass] attributes to target coverage precisely. With beStrictAboutCoverageMetadata="true", tests without coverage attributes are risky.

See ${CLAUDE_SKILL_DIR}/references/configuration.md for the full XML reference, coverage report types, and execution order options.

Application

When writing tests: apply all conventions silently — don't narrate each rule being followed. Match the project's existing test style. If an existing codebase contradicts a convention, follow the codebase and flag the divergence once.

When reviewing tests: cite the specific issue and show the fix inline. Don't lecture — state what's wrong and how to fix it.

Bad:  "According to PHPUnit best practices, you should use createStub
       instead of createMock when you don't need expectations..."
Good: "createMock → createStub (no expects() call, stub is sufficient)"

Integration

The php skill governs language choices; this skill governs PHPUnit testing decisions. The coding skill governs workflow (discovery, planning, verification).

Test behavior, not implementation. When in doubt, mock less.

Files (cc-foundry)
  • .dev
    • reference-inventory.json 948 B
      Loading…
  • references
    • assertions.md 5.8 KB
      Loading…
    • configuration.md 5.4 KB
      Loading…
    • data-providers.md 3.8 KB
      Loading…
    • mocking.md 4.9 KB
      Loading…
  • SKILL.md 16.3 KB
    ---
    name: phpunit
    description: >-
      PHPUnit testing framework conventions and practices. Invoke whenever task involves any
      interaction with PHPUnit — writing tests, configuring PHPUnit, data providers, mocking,
      assertions, debugging test failures, or coverage.
    ---
    
    # PHPUnit
    
    **Test behavior, not implementation. Tests are executable documentation — if the test name doesn't explain what the code
    does, rewrite it.**
    
    PHPUnit is PHP's standard testing framework. It uses test case classes extending `TestCase`, `setUp()`/`tearDown()` for
    fixtures, and a full assertion API. All patterns target PHPUnit 11+ on PHP 8.5+. Use PHP 8 attributes exclusively —
    annotations are deprecated in 11, removed in 12.
    
    ## References
    
    - **Assertion catalog, constraints, exception expectations** → [`${CLAUDE_SKILL_DIR}/references/assertions.md`] — Full
      assertion API grouped by category, constraint system, custom assertions
    - **Test doubles — stubs, mocks, MockBuilder** → [`${CLAUDE_SKILL_DIR}/references/mocking.md`] — createStub vs
      createMock, return config, invocation matchers, argument constraints, MockBuilder
    - **Data providers — static, named, generators** → [`${CLAUDE_SKILL_DIR}/references/data-providers.md`] —
      #[DataProvider], #[TestWith], named datasets, generator providers, external providers
    - **phpunit.xml structure, test suites, source config** → [`${CLAUDE_SKILL_DIR}/references/configuration.md`] — XML
      elements, strict settings, source element, coverage reports, execution order
    
    ## Test Structure
    
    ### Discovery and Naming
    
    - **Files:** `*Test.php` in configured test directories. Mirror source structure: `src/Service/PaymentService.php` →
      `tests/Unit/Service/PaymentServiceTest.php`.
    - **Classes:** `final class PaymentServiceTest extends TestCase`. Always `final`.
    - **Methods:** `test` prefix or `#[Test]` attribute. Describe the behavior: `testReturnsEmptyCollectionWhenNoResults`
      not `testSearch`.
    - **One test class per production class.** Split into Unit/Integration directories.
    
    ### Arrange-Act-Assert
    
    Structure every test in three phases:
    
    ```php
    public function testUserCreationSetsDefaults(): void
    {
        // Arrange
        $data = ['name' => 'Alice', 'email' => 'alice@example.com'];
    
        // Act
        $user = User::fromArray($data);
    
        // Assert
        $this->assertSame('Alice', $user->getName());
        $this->assertTrue($user->isActive());
        $this->assertSame([], $user->getRoles());
    }
    ```
    
    - **One act per test.** If you need multiple acts, write multiple tests.
    - **Comments optional** when phases are obvious. Add them when the test is long enough that phases aren't immediately
      clear.
    
    ### Test Granularity
    
    - **One concept per test.** Multiple assertions are fine when they verify the same behavior. Separate tests when
      behaviors are independent.
    - **Fast by default.** Unit tests should run in milliseconds. Gate slow tests behind groups: `#[Group('slow')]`.
    - **Isolation is mandatory.** Tests must not depend on execution order or shared mutable state. Each test sets up its
      own world.
    
    ## Fixtures
    
    ### setUp() / tearDown()
    
    - **`setUp()`** runs before each test method on a fresh instance. Create the SUT and its stubs here.
    - **`tearDown()`** runs after each test. Only needed for external resources (files, sockets, DB connections). Not needed
      for plain object cleanup.
    - **`setUpBeforeClass()` / `tearDownAfterClass()`** run once per class. Use for expensive shared resources (DB
      connections). Store in `static` properties.
    
    ```php
    final class PaymentServiceTest extends TestCase
    {
        private PaymentService $service;
        private Gateway&Stub $gateway;
    
        protected function setUp(): void
        {
            $this->gateway = $this->createStub(Gateway::class);
            $this->service = new PaymentService($this->gateway);
        }
    }
    ```
    
    ### Fixture Lifecycle
    
    - **`setUpBeforeClass()`** — Class scope; once before first test
    - **`setUp()`** — Method scope; before each test
    - **`assertPreConditions()`** — Method scope; after setUp, before test
    - **`assertPostConditions()`** — Method scope; after test, before tearDown
    - **`tearDown()`** — Method scope; after each test
    - **`tearDownAfterClass()`** — Class scope; once after last test
    - **Call `parent::setUp()`** when extending abstract test cases — otherwise parent fixture setup is silently skipped.
    - **Use `#[Before]` / `#[After]` attributes** when multiple setup methods are needed (avoids fragile `parent::setUp()`
      chains).
    
    ## Data Providers
    
    ### Basic Usage
    
    ```php
    use PHPUnit\Framework\Attributes\DataProvider;
    
    #[DataProvider('additionCases')]
    public function testAdd(int $a, int $b, int $expected): void
    {
        $this->assertSame($expected, $a + $b);
    }
    
    public static function additionCases(): array
    {
        return [
            'zeros'        => [0, 0, 0],
            'positive sum' => [1, 2, 3],
            'negative'     => [-1, 1, 0],
        ];
    }
    ```
    
    - **Providers must be `public static`.** Non-static providers are removed in PHPUnit 11.
    - **Always use named datasets** — string keys produce readable failure output.
    - **Use `#[DataProvider]` attribute**, not `@dataProvider` annotation.
    
    ### Inline Data
    
    For small, simple datasets — no provider method needed:
    
    ```php
    use PHPUnit\Framework\Attributes\TestWith;
    
    #[TestWith([0, 0, 0])]
    #[TestWith([1, 2, 3])]
    #[TestWith([-1, 1, 0])]
    public function testAdd(int $a, int $b, int $expected): void
    {
        $this->assertSame($expected, $a + $b);
    }
    ```
    
    ### Generator Providers
    
    For large or computed datasets:
    
    ```php
    public static function boundaryCases(): Generator
    {
        yield 'min int' => [PHP_INT_MIN, 0, PHP_INT_MIN];
        yield 'max int' => [PHP_INT_MAX, 0, PHP_INT_MAX];
    }
    ```
    
    ### Provider Rules
    
    - **Data must be scalar or immutable** — no service objects or complex graphs in providers.
    - **No mock objects in providers** — framework isn't initialized during provider execution.
    - **Empty providers are forbidden** in PHPUnit 11 — throws `InvalidDataProviderException`.
    - **Multiple providers** can be stacked on one test method — datasets are combined.
    
    See `${CLAUDE_SKILL_DIR}/references/data-providers.md` for external providers, TestDox integration, and edge cases.
    
    ## Assertions
    
    ### Core Assertions
    
    ```php
    $this->assertSame($expected, $actual);        // Strict === (preferred)
    $this->assertEquals($expected, $actual);       // Loose == (use sparingly)
    $this->assertTrue($condition);
    $this->assertFalse($condition);
    $this->assertNull($value);
    $this->assertInstanceOf(Expected::class, $obj);
    $this->assertCount(3, $collection);
    $this->assertEmpty($collection);
    $this->assertArrayHasKey('key', $array);
    $this->assertContains($needle, $haystack);     // Strict comparison
    ```
    
    - **Prefer `assertSame()` over `assertEquals()`** — strict type comparison catches more bugs.
    - **Multiple assertions per test are fine** when they verify the same behavior.
    
    ### String Assertions
    
    ```php
    $this->assertStringStartsWith('Error:', $message);
    $this->assertStringEndsWith('.php', $filename);
    $this->assertStringContainsString('needle', $haystack);
    $this->assertMatchesRegularExpression('/^\d{4}-\d{2}$/', $date);
    ```
    
    ### Float Comparison
    
    ```php
    $this->assertEqualsWithDelta(3.14, $result, 0.01);
    ```
    
    ### Exception Testing
    
    ```php
    public function testThrowsOnInvalidInput(): void
    {
        $this->expectException(InvalidArgumentException::class);
        $this->expectExceptionMessage('must be positive');
    
        $calculator->divide(1, 0);
    }
    ```
    
    - **Call `expectException()` before the throwing code** — it sets up the expectation.
    - **Use `expectExceptionMessage()`** when the exception type is broad — validates the message contains the substring.
    - **Use `expectExceptionMessageMatches()`** for regex matching.
    
    ### Deprecation / Error Expectations
    
    ```php
    public function testTriggersDeprecation(): void
    {
        $this->expectUserDeprecationMessage('use newMethod() instead');
    
        $service->oldMethod();
    }
    ```
    
    See `${CLAUDE_SKILL_DIR}/references/assertions.md` for the full assertion catalog, constraint system, and format string
    assertions.
    
    ## Mocking
    
    ### Stubs vs Mocks
    
    - **Stub** (`createStub()`) — controls return values. No call verification.
    - **Mock** (`createMock()`) — verifies interactions (method called, arguments matched).
    
    **Use stubs by default. Use mocks only when verifying that a side effect occurred.**
    
    ### Creating Stubs
    
    ```php
    $repo = $this->createStub(UserRepository::class);
    $repo->method('find')->willReturn(new User(name: 'Alice'));
    
    $service = new UserService($repo);
    $result = $service->getUser(1);
    
    $this->assertSame('Alice', $result->name);
    ```
    
    Shorthand for multiple methods:
    
    ```php
    $repo = $this->createConfiguredStub(UserRepository::class, [
        'find'   => new User(name: 'Alice'),
        'exists' => true,
    ]);
    ```
    
    ### Creating Mocks
    
    ```php
    $logger = $this->createMock(Logger::class);
    $logger->expects($this->once())
        ->method('error')
        ->with($this->stringContains('payment failed'));
    
    $service = new PaymentService($logger);
    $service->process($invalidPayment);
    ```
    
    ### Return Value Configuration
    
    ```php
    $stub->method('fetch')->willReturn('value');              // Fixed value
    $stub->method('fetch')->willReturn('a', 'b', 'c');       // Consecutive values
    $stub->method('fetch')->willReturnArgument(0);            // Return first arg
    $stub->method('fetch')->willReturnSelf();                 // Fluent interface
    $stub->method('fetch')->willReturnCallback(fn ($id) => "item-{$id}");
    $stub->method('fetch')->willThrowException(new RuntimeException('fail'));
    $stub->method('fetch')->willReturnMap([
        ['key1', 'value1'],
        ['key2', 'value2'],
    ]);
    ```
    
    ### Mocking Rules
    
    - **Mock at boundaries.** Mock external services, databases, filesystems, clocks — not internal functions.
    - **Don't mock what you own** when a fake or in-memory implementation is available.
    - **Prefer dependency injection** over complex mock setup. Pass collaborators as constructor parameters, stub in tests.
    - **Never mock the thing you're testing.** If you need to mock part of the SUT, the SUT has too many responsibilities —
      split it.
    - **Favour interfaces over classes** for test doubles — fewer limitations, better design.
    - **Do not call `expects()` on stubs** — deprecated in 11, error in 12.
    
    See `${CLAUDE_SKILL_DIR}/references/mocking.md` for MockBuilder, intersection types, invocation matchers, and PHP 8.4
    property hooks.
    
    ## Attributes
    
    PHPUnit 11 uses PHP 8 attributes exclusively. All attributes are in the `PHPUnit\Framework\Attributes` namespace.
    
    ### Test Metadata
    
    - **`#[Test]`** — Mark non-`test*` method as a test
    - **`#[DataProvider('method')]`** — Connect a data provider
    - **`#[DataProviderExternal(Class::class, 'method')]`** — External data provider
    - **`#[TestWith([args])]`** — Inline data provider
    - **`#[TestDox('description')]`** — Custom TestDox description
    - **`#[Depends('testMethod')]`** — Declare test dependency
    - **`#[Group('name')]`** — Assign to group
    - **`#[Ticket('PROJ-123')]`** — Link to issue tracker
    
    ### Skip / Conditional
    
    - **`#[RequiresPhp('>= 8.4')]`** — Skip if PHP version doesn't match
    - **`#[RequiresPhpExtension('pdo_pgsql')]`** — Skip if extension missing
    - **`#[RequiresOperatingSystemFamily('Linux')]`** — Skip on other OS
    - **`#[RequiresFunction('sodium_crypto_sign')]`** — Skip if function missing
    - **`#[RequiresMethod(PDO::class, 'sqliteCreateFunction')]`** — Skip if method missing
    
    ### Coverage
    
    - **`#[CoversClass(ClassName::class)]`** — Test covers this class
    - **`#[CoversFunction('functionName')]`** — Test covers this function
    - **`#[CoversMethod(ClassName::class, 'method')]`** — Test covers this method
    - **`#[CoversNothing]`** — Test contributes no coverage (integration tests)
    - **`#[UsesClass(ClassName::class)]`** — Allowed but not covered dependency
    - **`#[UsesFunction('functionName')]`** — Allowed but not covered function
    
    ### Fixture
    
    - **`#[Before]`** — Run method before each test (alternative to setUp)
    - **`#[After]`** — Run method after each test (alternative to tearDown)
    - **`#[BeforeClass]`** — Run static method before first test
    - **`#[AfterClass]`** — Run static method after last test
    - **`#[BackupGlobals(true)]`** — Backup/restore globals for this test
    - **`#[BackupStaticProperties(true)]`** — Backup/restore static properties
    
    ### Test Behavior
    
    - **`#[DoesNotPerformAssertions]`** — Suppress risky test warning
    - **`#[RunInSeparateProcess]`** — Isolate in separate PHP process
    - **`#[RunTestsInSeparateProcesses]`** — All tests in class run isolated
    - **`#[Small]` / `#[Medium]` / `#[Large]`** — Time limit enforcement (1s/10s/60s)
    
    ## Test Organization
    
    ### Directory Structure
    
    ```text
    tests/
    ├── Unit/                     # Fast, isolated, no I/O
    │   ├── Service/
    │   │   └── PaymentServiceTest.php
    │   └── Model/
    │       └── UserTest.php
    ├── Integration/              # Real dependencies, slower
    │   └── Repository/
    │       └── UserRepositoryTest.php
    └── bootstrap.php             # Autoloader for tests
    ```
    
    - **Mirror source directory structure** under `tests/Unit/` and `tests/Integration/`.
    - **Unit tests** — no database, no filesystem, no network. Mock all boundaries.
    - **Integration tests** — real dependencies. Mark with `#[CoversNothing]` to avoid polluting coverage metrics.
    
    ### Test Suites
    
    Define in `phpunit.xml` for selective execution:
    
    ```xml
    <testsuites>
        <testsuite name="unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="integration">
            <directory>tests/Integration</directory>
        </testsuite>
    </testsuites>
    ```
    
    Run subsets: `phpunit --testsuite unit`, `phpunit --group slow`.
    
    ## Configuration
    
    ### Recommended phpunit.xml
    
    ```xml
    <?xml version="1.0" encoding="UTF-8"?>
    <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/11.5/phpunit.xsd"
             bootstrap="vendor/autoload.php"
             colors="true"
             cacheDirectory=".phpunit.cache"
             executionOrder="depends,random"
             beStrictAboutTestsThatDoNotTestAnything="true"
             beStrictAboutOutputDuringTests="true"
             failOnWarning="true"
             failOnRisky="true"
             failOnDeprecation="true"
             failOnNotice="true">
        <testsuites>
            <testsuite name="unit">
                <directory>tests/Unit</directory>
            </testsuite>
            <testsuite name="integration">
                <directory>tests/Integration</directory>
            </testsuite>
        </testsuites>
        <source restrictDeprecations="true"
                restrictNotices="true"
                restrictWarnings="true">
            <include>
                <directory suffix=".php">src</directory>
            </include>
        </source>
    </phpunit>
    ```
    
    ### Key Configuration Choices
    
    - **`executionOrder="depends,random"`** — randomize test order to catch hidden dependencies while respecting explicit
      `#[Depends]`.
    - **`beStrictAboutTestsThatDoNotTestAnything="true"`** — flag tests without assertions as risky.
    - **`failOnDeprecation="true"`** — catch deprecations from your code early.
    - **`<source>` with `restrictDeprecations`** — only surface issues from your code, not vendor dependencies.
    - **`cacheDirectory`** — add `.phpunit.cache` to `.gitignore`.
    
    ### Code Coverage
    
    Requires PCOV or Xdebug extension:
    
    ```bash
    phpunit --coverage-html build/coverage --coverage-clover build/clover.xml
    ```
    
    Use `#[CoversClass]` and `#[UsesClass]` attributes to target coverage precisely. With
    `beStrictAboutCoverageMetadata="true"`, tests without coverage attributes are risky.
    
    See `${CLAUDE_SKILL_DIR}/references/configuration.md` for the full XML reference, coverage report types, and execution
    order options.
    
    ## Application
    
    When **writing** tests: apply all conventions silently — don't narrate each rule being followed. Match the project's
    existing test style. If an existing codebase contradicts a convention, follow the codebase and flag the divergence once.
    
    When **reviewing** tests: cite the specific issue and show the fix inline. Don't lecture — state what's wrong and how to
    fix it.
    
    ```text
    Bad:  "According to PHPUnit best practices, you should use createStub
           instead of createMock when you don't need expectations..."
    Good: "createMock → createStub (no expects() call, stub is sufficient)"
    ```
    
    ## Integration
    
    The **php** skill governs language choices; this skill governs PHPUnit testing decisions. The **coding** skill governs
    workflow (discovery, planning, verification).
    
    **Test behavior, not implementation. When in doubt, mock less.**
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.