Testing Knowledge Base

Quick reference for PHP testing patterns, principles, and best practices.

Testing Pyramid

        /\
       /  \     Functional (10%)
      /────\    - E2E, browser tests
     /      \   - Slow, fragile
    /────────\  Integration (20%)
   /          \ - DB, HTTP, queues
  /────────────\Unit (70%)
 /              \- Fast, isolated
/________________\- Business logic

Rule: 70% unit, 20% integration, 10% functional. Invert the pyramid = slow, brittle test suite.

AAA Pattern (Arrange-Act-Assert)

public function test_order_calculates_total_with_discount(): void
{
    // Arrange — set up test data
    $order = new Order(OrderId::generate());
    $order->addItem(new Product('Book', Money::EUR(100)));
    $discount = new PercentageDiscount(10);

    // Act — execute the behavior
    $total = $order->calculateTotal($discount);

    // Assert — verify the outcome
    self::assertEquals(Money::EUR(90), $total);
}

Rules:

• One blank line between sections
• Single Act per test
• Assert behavior, not implementation

Naming Conventions

PHPUnit Style

test_{method}_{scenario}_{expected}

Example	Method	Scenario	Expected
test_calculate_total_with_discount_returns_reduced_amount	calculateTotal	with discount	returns reduced amount
test_confirm_when_already_shipped_throws_exception	confirm	when already shipped	throws exception
test_email_with_invalid_format_fails_validation	Email (VO)	with invalid format	fails validation

Pest Style

it('calculates total with discount applied')
it('throws exception when confirming shipped order')
it('fails validation for invalid email format')

Test Isolation Principles

DO

• Fresh fixtures per test
• Independent test execution (any order)
• Teardown cleans all state
• Use in-memory implementations

DON'T

• Shared mutable state between tests
• Tests depending on execution order
• Global variables or singletons
• Real external services in unit tests

Quick Quality Checklist

Rule	Check
One test = one behavior	Single assertion group
Test is documentation	Name reads as specification
No logic in tests	No if/for/while
Fast execution	<100ms per unit test
Mock interfaces only	Never mock VO, Entity, final
≤3 mocks per test	More = design smell
Behavior over implementation	Test WHAT, not HOW

DDD Component Testing

Component	Test Focus	Mocks Allowed
Value Object	Validation, equality, immutability	None
Entity	State transitions, business rules	None
Aggregate	Invariants, consistency, events	None
Domain Service	Business logic spanning aggregates	Repository (Fake)
Application Service	Orchestration, transactions	Repository, EventDispatcher
Repository	CRUD operations	Database (SQLite)

PHP 8.4 Test Patterns

Unit Test Template

<?php

declare(strict_types=1);

namespace Tests\Unit\Domain;

use PHPUnit\Framework\Attributes\CoversClass;
use PHPUnit\Framework\Attributes\Group;
use PHPUnit\Framework\TestCase;

#[Group('unit')]
#[CoversClass(Email::class)]
final class EmailTest extends TestCase
{
    public function test_creates_valid_email(): void
    {
        $email = new Email('user@example.com');

        self::assertSame('user@example.com', $email->value);
    }

    public function test_throws_for_invalid_format(): void
    {
        $this->expectException(InvalidArgumentException::class);

        new Email('invalid');
    }
}

Integration Test Template

<?php

declare(strict_types=1);

namespace Tests\Integration\Infrastructure;

use PHPUnit\Framework\Attributes\Group;
use Tests\DatabaseTestCase;

#[Group('integration')]
final class DoctrineOrderRepositoryTest extends DatabaseTestCase
{
    private OrderRepositoryInterface $repository;

    protected function setUp(): void
    {
        parent::setUp();
        $this->repository = $this->getContainer()->get(OrderRepositoryInterface::class);
    }

    public function test_saves_and_retrieves_order(): void
    {
        // Arrange
        $order = OrderMother::pending();

        // Act
        $this->repository->save($order);
        $found = $this->repository->findById($order->id());

        // Assert
        self::assertNotNull($found);
        self::assertTrue($order->id()->equals($found->id()));
    }
}

Test Doubles Quick Reference

Type	Purpose	When to Use
Stub	Returns canned answers	External API responses
Mock	Verifies interactions	Event publishing
Fake	Working implementation	InMemory repository
Spy	Records calls	Logging, notifications

Decision Matrix

Need to verify a call was made?
├── Yes → Mock or Spy
└── No → Need real behavior?
    ├── Yes → Fake
    └── No → Stub

Common Test Smells

Smell	Detection	Fix
Logic in Test	if, for, while in test	Extract to helper or parameterize
Mock Overuse	>3 mocks	Refactor design, use Fakes
Mystery Guest	External files, hidden data	Inline test data or use Builder
Eager Test	Tests multiple behaviors	Split into separate tests
Fragile Test	Breaks on refactor	Test behavior, not implementation

Advanced Testing Patterns

Contract Testing (Pact)

Aspect	Unit Test	Integration Test	Contract Test
Speed	Fast	Slow	Medium
Scope	Single class	Service + deps	API boundary
Isolation	Full	Partial	Consumer/Provider
Use case	Business logic	DB, queues	Service-to-service

When to use: Microservices REST APIs, message-based systems, event schema verification.

Load Testing Patterns

Pattern	Duration	Load Profile	Goal
Smoke	1-2 min	Minimal	Verify script works
Load	10-30 min	Expected traffic	Performance baseline
Stress	10-30 min	1.5-2x expected	Find breaking point
Spike	5-10 min	Sudden burst	Test auto-scaling
Soak	2-8 hours	Sustained	Find memory leaks

Chaos Testing (Failure Injection)

Failure	How to Inject	What It Tests
Network latency	Sleep in middleware	Timeout handling
Service error	Return 500 randomly	Circuit breaker
Connection refused	Close port	Fallback behavior
Slow database	Query delay	Query timeout handling

E2E Distributed Testing

Strategy	How	Trade-off
Test containers	Docker Compose per test	Isolated but slow
Shared staging	Dedicated environment	Fast but interference
Data seeding	API/DB setup per test	Controlled but complex
Snapshot restore	DB snapshot before tests	Fast reset

References

For detailed information, load these reference files:

• references/unit-testing.md — Unit test patterns and examples
• references/integration-testing.md — Integration test setup and patterns
• references/ddd-testing.md — Testing DDD components (VO, Entity, Aggregate, Service)
• references/advanced-testing.md — Contract testing (Pact), chaos testing, load testing patterns (ramp-up, spike, soak), E2E distributed testing