In this chapter, we'll explore the use of datasets in PestPHP, a feature that allows you to define an array of test data, enabling PestPHP to automatically run the same test for each set. This is particularly valuable when you want to ensure that your code behaves consistently across various scenarios.

Understanding Datasets

Datasets in PestPHP provide a concise and powerful way to test multiple cases with minimal duplication of code. Instead of writing separate tests for each scenario, you can define an array of test data and let PestPHP iterate through them, running the same test logic for each set.

Basic Usage of Datasets

Let's start with a basic example. Suppose you have a function that adds two numbers, and you want to test it with different inputs:

test('addition works with datasets')
    ->with([
        [1, 2, 3],
        [0, 0, 0],
        [-1, 1, 0],
    ])
    ->test(function ($a, $b, $expected) {
        expect($a + $b)->toBe($expected);
    });

In this example, the with method is used to define an array of datasets, where each dataset contains values for $a, $b, and the expected result. PestPHP will then automatically run the test for each set, making it easy to cover various scenarios.

Key-Value Datasets

You can also use key-value pairs in your datasets to make the test data more readable and descriptive:

test('string contains substring')
    ->with([
        ['hello world', 'hello', true],
        ['hello world', 'foo', false],
    ])
    ->test(function ($string, $substring, $expected) {
        expect(strpos($string, $substring) !== false)->toBe($expected);
    });

In this example, each dataset consists of a $string, a $substring, and the expected result. The test logic remains the same, and PestPHP handles the iteration through the datasets.

Advanced Dataset Features

PestPHP provides additional features to enhance dataset testing:

Dataset Key Naming

You can name the keys in your datasets to make the test output more descriptive:

test('divide numbers')
    ->with([
        'valid division' => [6, 2, 3],
        'divide by zero' => [8, 0, 'exception' => DivisionByZeroError::class],
    ])
    ->test(function ($a, $b, $expected) {
        if ($expected === 'exception') {
            expect(fn() => $a / $b)->toThrow($expected);
        } else {
            expect($a / $b)->toBe($expected);
        }
    });

Dynamic Datasets

You can use a closure to dynamically generate datasets at runtime:

test('dynamic datasets')
    ->with(function () {
        return [
            [1, 2, 3],
            [0, 0, 0],
            [-1, 1, 0],
        ];
    })
    ->test(function ($a, $b, $expected) {
        expect($a + $b)->toBe($expected);
    });

This can be useful when the dataset generation logic is more complex.

Conclusion

Datasets in PestPHP provide a streamlined way to test your code across various scenarios. By defining sets of test data, you can ensure that your code behaves consistently and correctly in different situations. Leveraging PestPHP's dataset features can significantly reduce code duplication and make your test suite more concise and maintainable. In the next chapter, we will explore the integration of PestPHP with popular testing frameworks, extending its capabilities and compatibility.