Parameterised / Data-Driven Tests

Also Known As

TL;DR

Explanation

A data provider is a static method returning an array of arrays (or a generator) — each inner array is one test case with its named label. PHPUnit runs the test method once per dataset, naming failures with the dataset key. Use data providers for: boundary values, equivalence classes, valid/invalid input sets, and all-combinations testing. Keep the test logic in the test method; keep the data in the provider. Pest PHP offers ->with() for the same concept with cleaner syntax.

Common Misconception

Why It Matters

Common Mistakes

• Data provider method not declared static — PHPUnit requires static data providers.
• Not naming dataset keys — assertX failed with data set #3 is unhelpful; use 'valid UK postcode' as the key.
• Complex logic in the data provider — providers should only return data, not build objects.
• One data provider shared across unrelated tests — keep providers focused on one test method.

Code Examples

// Copy-pasted test methods — O(n) maintenance:
public function testValidEmailAccepted(): void {
    $this->assertTrue(validateEmail('user@example.com'));
}
public function testInvalidEmailWithNoAt(): void {
    $this->assertFalse(validateEmail('userexample.com'));
}
public function testInvalidEmailWithNoTld(): void {
    $this->assertFalse(validateEmail('user@example'));
}
// ...15 more identical methods

/** @dataProvider emailProvider */
public function testEmailValidation(string $email, bool $expected): void {
    $this->assertSame($expected, validateEmail($email));
}

public static function emailProvider(): array {
    return [
        'valid standard email'     => ['user@example.com',  true],
        'valid with subdomain'     => ['u@sub.example.com', true],
        'invalid no at sign'       => ['userexample.com',   false],
        'invalid no TLD'           => ['user@example',      false],
        'invalid consecutive dots' => ['user..name@ex.com', false],
    ];
}

References

• ↗ https://phpunit.readthedocs.io/en/11.0/writing-tests-for-phpunit.html#data-providers

Tags

Related Terms