PHPUnit Testing Skill

You are an expert PHP developer specializing in testing with PHPUnit. When the user asks you to write, review, or debug PHPUnit tests, follow these detailed instructions to produce well-structured, comprehensive test suites that ensure PHP application reliability.

Core Principles

1. Test behavior, not implementation -- Verify what the code does from a caller's perspective, not how it achieves the result internally.
2. One logical assertion per test -- Each test method should verify a single behavior so failures pinpoint the exact issue.
3. Arrange-Act-Assert -- Structure every test into setup, execution, and verification phases for clarity.
4. Isolate external dependencies -- Use mocks and stubs to eliminate database calls, HTTP requests, and file system access from unit tests.
5. Descriptive test names -- Name tests as

   test_<method>_<scenario>_<expected>

   or use

   @test

   annotation with snake_case descriptions.
6. Use data providers for parameterization -- Leverage

   @dataProvider

   to test multiple input/output combinations without duplicating test methods.
7. Strict type checking -- Prefer

   assertSame

   over

   assertEquals

   when type identity matters to catch subtle type coercion bugs.

Project Structure

project/
  src/
    Service/
      UserService.php
      PaymentService.php
    Model/
      User.php
      Order.php
    Repository/
      UserRepository.php
    Util/
      Validators.php
  tests/
    Unit/
      Service/
        UserServiceTest.php
        PaymentServiceTest.php
      Model/
        UserTest.php
        OrderTest.php
      Util/
        ValidatorsTest.php
    Integration/
      UserPaymentFlowTest.php
    Fixtures/
      TestDataFactory.php
    bootstrap.php
  phpunit.xml
  composer.json

Configuration

phpunit.xml

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="tests/bootstrap.php"
         colors="true"
         failOnRisky="true"
         failOnWarning="true"
         stopOnFailure="false">
    <testsuites>
        <testsuite name="Unit">
            <directory>tests/Unit</directory>
        </testsuite>
        <testsuite name="Integration">
            <directory>tests/Integration</directory>
        </testsuite>
    </testsuites>
    <coverage>
        <include>
            <directory suffix=".php">src</directory>
        </include>
    </coverage>
</phpunit>

composer.json

{
    "require-dev": {
        "phpunit/phpunit": "^11.0",
        "mockery/mockery": "^1.6"
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    },
    "scripts": {
        "test": "phpunit",
        "test:unit": "phpunit --testsuite=Unit",
        "test:coverage": "phpunit --coverage-html coverage"
    }
}

Running Tests

# Run all tests
./vendor/bin/phpunit

# Run specific suite
./vendor/bin/phpunit --testsuite=Unit

# Run specific test file
./vendor/bin/phpunit tests/Unit/Service/UserServiceTest.php

# Run specific test method
./vendor/bin/phpunit --filter test_create_user_with_valid_data

# Run with coverage
./vendor/bin/phpunit --coverage-html coverage

# Run specific group
./vendor/bin/phpunit --group unit

Basic Test Structure

<?php

declare(strict_types=1);

namespace Tests\Unit\Service;

use App\Service\UserService;
use App\Model\User;
use App\Repository\UserRepository;
use PHPUnit\Framework\TestCase;

class UserServiceTest extends TestCase
{
    private UserService $userService;
    private UserRepository $userRepository;

    protected function setUp(): void
    {
        parent::setUp();
        $this->userRepository = new InMemoryUserRepository();
        $this->userService = new UserService($this->userRepository);
    }

    protected function tearDown(): void
    {
        parent::tearDown();
    }

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

        $user = $this->userService->createUser($data);

        $this->assertInstanceOf(User::class, $user);
        $this->assertSame('Alice', $user->getName());
        $this->assertSame('alice@example.com', $user->getEmail());
    }

    public function test_create_user_without_email_throws_exception(): void
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->expectExceptionMessage('email');

        $this->userService->createUser(['name' => 'Bob']);
    }

    public function test_create_user_with_duplicate_email_throws_exception(): void
    {
        $data = ['name' => 'Alice', 'email' => 'alice@example.com', 'age' => 30];
        $this->userService->createUser($data);

        $this->expectException(DuplicateEmailException::class);

        $this->userService->createUser($data);
    }
}

Assertion Methods Reference

class AssertionExamplesTest extends TestCase
{
    public function test_equality_assertions(): void
    {
        $this->assertEquals(4, 2 + 2);           // Loose comparison
        $this->assertSame(4, 2 + 2);             // Strict comparison (type + value)
        $this->assertNotEquals(5, 2 + 2);
        $this->assertNotSame('4', 4);             // Different types
        $this->assertEqualsWithDelta(0.3, 0.1 + 0.2, 0.001);
    }

    public function test_boolean_assertions(): void
    {
        $this->assertTrue(10 > 5);
        $this->assertFalse(5 > 10);
        $this->assertNull(null);
        $this->assertNotNull('value');
        $this->assertEmpty([]);
        $this->assertNotEmpty([1, 2, 3]);
    }

    public function test_type_assertions(): void
    {
        $this->assertIsInt(42);
        $this->assertIsString('hello');
        $this->assertIsArray([1, 2, 3]);
        $this->assertIsBool(true);
        $this->assertIsFloat(3.14);
        $this->assertInstanceOf(\DateTime::class, new \DateTime());
    }

    public function test_string_assertions(): void
    {
        $this->assertStringContainsString('world', 'hello world');
        $this->assertStringStartsWith('hello', 'hello world');
        $this->assertStringEndsWith('world', 'hello world');
        $this->assertMatchesRegularExpression('/\d+/', 'abc123');
        $this->assertStringContainsStringIgnoringCase('WORLD', 'hello world');
    }

    public function test_array_assertions(): void
    {
        $this->assertContains(2, [1, 2, 3]);
        $this->assertNotContains(4, [1, 2, 3]);
        $this->assertCount(3, [1, 2, 3]);
        $this->assertArrayHasKey('name', ['name' => 'Alice']);
    }

    public function test_json_assertions(): void
    {
        $expected = '{"name":"Alice","age":30}';
        $actual = '{"age":30,"name":"Alice"}';
        $this->assertJsonStringEqualsJsonString($expected, $actual);
    }

    public function test_exception_assertions(): void
    {
        $this->expectException(\DivisionByZeroError::class);

        $result = 1 / 0;
    }
}

Data Providers

class ValidatorTest extends TestCase
{
    /**
     * @dataProvider validEmailProvider
     */
    public function test_is_valid_email_with_valid_input(string $email): void
    {
        $this->assertTrue(Validators::isValidEmail($email));
    }

    public static function validEmailProvider(): array
    {
        return [
            'simple email' => ['user@example.com'],
            'dotted name' => ['user.name@domain.org'],
            'plus tag' => ['user+tag@example.co.uk'],
            'numeric' => ['user123@test.io'],
        ];
    }

    /**
     * @dataProvider invalidEmailProvider
     */
    public function test_is_valid_email_with_invalid_input(string $email): void
    {
        $this->assertFalse(Validators::isValidEmail($email));
    }

    public static function invalidEmailProvider(): array
    {
        return [
            'empty string' => [''],
            'no at sign' => ['not-an-email'],
            'no local part' => ['@domain.com'],
            'no domain' => ['user@'],
            'space in email' => ['user @domain.com'],
        ];
    }

    /**
     * @dataProvider calculatorProvider
     */
    public function test_add_with_various_inputs(int $a, int $b, int $expected): void
    {
        $this->assertSame($expected, Calculator::add($a, $b));
    }

    public static function calculatorProvider(): array
    {
        return [
            'positive numbers' => [1, 1, 2],
            'zeros' => [0, 0, 0],
            'negative and positive' => [-1, 1, 0],
            'large numbers' => [100, 200, 300],
            'both negative' => [-50, -50, -100],
        ];
    }
}

Mocking with PHPUnit

class UserServiceMockTest extends TestCase
{
    private UserService $userService;
    private UserRepository $mockRepository;
    private EmailService $mockEmailService;

    protected function setUp(): void
    {
        $this->mockRepository = $this->createMock(UserRepository::class);
        $this->mockEmailService = $this->createMock(EmailService::class);
        $this->userService = new UserService($this->mockRepository, $this->mockEmailService);
    }

    public function test_get_user_by_id_queries_repository(): void
    {
        $expectedUser = new User('Alice', 'alice@example.com', 30);

        $this->mockRepository
            ->expects($this->once())
            ->method('findById')
            ->with(1)
            ->willReturn($expectedUser);

        $user = $this->userService->getUser(1);

        $this->assertSame('Alice', $user->getName());
    }

    public function test_get_user_not_found_returns_null(): void
    {
        $this->mockRepository
            ->expects($this->once())
            ->method('findById')
            ->with(999)
            ->willReturn(null);

        $user = $this->userService->getUser(999);

        $this->assertNull($user);
    }

    public function test_create_user_sends_welcome_email(): void
    {
        $this->mockRepository
            ->expects($this->once())
            ->method('save')
            ->willReturnCallback(function (User $user) {
                $user->setId(1);
                return $user;
            });

        $this->mockEmailService
            ->expects($this->once())
            ->method('sendWelcome')
            ->with($this->callback(function ($email) {
                return $email === 'bob@example.com';
            }));

        $this->userService->createUser([
            'name' => 'Bob',
            'email' => 'bob@example.com',
        ]);
    }

    public function test_create_user_handles_email_failure(): void
    {
        $this->mockRepository->method('save')->willReturnCallback(function (User $user) {
            $user->setId(1);
            return $user;
        });

        $this->mockEmailService
            ->method('sendWelcome')
            ->willThrowException(new \RuntimeException('SMTP error'));

        // Should not throw even when email fails
        $user = $this->userService->createUser([
            'name' => 'Bob',
            'email' => 'bob@example.com',
        ]);

        $this->assertSame(1, $user->getId());
    }
}

Test Doubles: Stubs and Fakes

class PaymentServiceTest extends TestCase
{
    public function test_process_payment_with_stub_gateway(): void
    {
        $gateway = $this->createStub(PaymentGateway::class);
        $gateway->method('charge')->willReturn([
            'status' => 'success',
            'txn_id' => 'abc123'
        ]);

        $service = new PaymentService($gateway);
        $result = $service->processPayment(50.00, 'tok_123');

        $this->assertSame('success', $result['status']);
    }

    public function test_process_payment_retries_on_failure(): void
    {
        $gateway = $this->createStub(PaymentGateway::class);
        $gateway->method('charge')
            ->willReturnOnConsecutiveCalls(
                $this->throwException(new \RuntimeException('timeout')),
                $this->throwException(new \RuntimeException('timeout')),
                ['status' => 'success', 'txn_id' => 'def456']
            );

        $service = new PaymentService($gateway);
        $result = $service->processPayment(50.00, 'tok_123');

        $this->assertSame('success', $result['status']);
    }
}

Lifecycle Methods

class LifecycleExampleTest extends TestCase
{
    private static $sharedConnection;

    public static function setUpBeforeClass(): void
    {
        // Runs once before ALL tests in this class
        self::$sharedConnection = new DatabaseConnection('sqlite::memory:');
    }

    public static function tearDownAfterClass(): void
    {
        // Runs once after ALL tests in this class
        self::$sharedConnection = null;
    }

    protected function setUp(): void
    {
        // Runs before EACH test
        parent::setUp();
        self::$sharedConnection->beginTransaction();
    }

    protected function tearDown(): void
    {
        // Runs after EACH test
        self::$sharedConnection->rollBack();
        parent::tearDown();
    }

    public function test_insert_user(): void
    {
        self::$sharedConnection->exec(
            "INSERT INTO users (name) VALUES ('Alice')"
        );

        $result = self::$sharedConnection->query("SELECT name FROM users")->fetch();
        $this->assertSame('Alice', $result['name']);
    }
}

Best Practices

1. Use

   assertSame

   over

   assertEquals

   when type matters --

   assertEquals

   does type coercion;

   assertSame

   catches

   '1' !== 1

   bugs that loose comparison misses.
2. Use data providers for multiple inputs -- Extract test data into

   @dataProvider

   methods with descriptive keys for clean, maintainable parameterized tests.
3. Name data provider keys descriptively -- Use strings like

   'empty string'

   and

   'no at sign'

   so PHPUnit output shows which case failed.
4. Mock only external dependencies -- Mock database repositories, HTTP clients, and third-party APIs; do not mock value objects or simple utilities.
5. Use

   setUp

   and

   tearDown

   consistently -- Initialize shared objects in

   setUp

   and clean up in

   tearDown

   for test isolation.
6. Prefer constructor injection -- Design classes with dependency injection for easy mocking in tests without reflection hacks.
7. Test exceptions with

   expectException

   -- Verify both the exception class and message using

   expectExceptionMessage

   for precise error testing.
8. Use

   @group

   annotations -- Tag tests as unit, integration, or slow for selective execution with

   --group

   and

   --exclude-group

   .
9. Enable strict mode in phpunit.xml -- Set

   failOnRisky="true"

   and

   failOnWarning="true"

   to catch tests that do not assert anything.
10. Run with coverage to find gaps -- Use

    --coverage-html

    to generate visual reports showing which code paths lack test coverage.

Anti-Patterns

1. Using

   assertEquals

   when

   assertSame

   is needed -- Loose comparison hides type coercion bugs; always use strict comparison for scalars.
2. Not using data providers -- Copy-pasting test methods with different inputs creates maintenance burden; use

   @dataProvider

   instead.
3. Testing private methods via reflection -- Accessing private methods couples tests to implementation; test through public API.
4. Ignoring

   setUp

   /

   tearDown

   -- Duplicating setup code in every test method is verbose and fragile when requirements change.
5. Over-mocking -- Mocking every class including value objects makes tests prove nothing about real behavior.
6. Not testing error paths -- Only testing the happy path means exception handling is unverified and may fail in production.
7. Hardcoding file paths -- Using absolute paths breaks tests on other machines; use

   sys_get_temp_dir()

   and

   tempnam()

   .
8. Shared mutable state -- Static properties modified by tests cause order-dependent failures; reset state in

   setUp

   .
9. Large test methods -- Tests exceeding 20 lines usually verify too many things; split into focused methods.
10. Not running in strict mode -- Without

    failOnRisky

    , tests that assert nothing pass silently, giving false confidence.