sebdd

thoughts and inspiration on designing, programming, and writing for the web

Tabular assertions with PHPUnit

9 Jan 2024

With tabular assertions, you describe the expected outcome in a markdown-like table format. Here's why there useful, and how to use tabular assertions with PHPUnit.

This is a tabular test in PHPUnit:

use PHPUnit\Framework\TestCase;
use Spatie\TabularAssertions\PHPUnit\TabularAssertions;
 
class OrderLogTest extends TestCase
{
    use TabularAssertions;
 
    public function test_it_logs_order_activity(): void
    {
        $order = OrderFactory::create()
            ->withPrice(100_00)
            ->withTaxRates([5_00, 10_00])
            ->withShipping(5_00)
            ->paid();
 
        $this->assertMatchesTable('
            | type        | reason   | #product_id | #tax_id | #shipping_id | #payment_id |  price |  paid  |
            | product     | created  |          #1 |         |              |             | 100_00 |   0_00 |
            | tax         | created  |             |      #1 |              |             |   5_00 |   0_00 |
            | tax         | created  |             |      #2 |              |             |  10_00 |   0_00 |
            | shipping    | created  |             |         |           #1 |             |   5_00 |   0_00 |
            | product     | paid     |          #1 |         |              |          #1 |   0_00 | 100_00 |
            | tax         | paid     |             |      #1 |              |          #1 |   0_00 |   5_00 |
            | tax         | paid     |             |      #2 |              |          #1 |   0_00 |  10_00 |
            | shipping    | paid     |             |         |           #1 |          #1 |   0_00 |   5_00 |
        ', $order->activity);
    }
}

Before we dive into the how-to, lets review why tabular assertions are useful.

Lots of data at a glance

Text-based tables are compact. If we want to assert the same data with assert methods, we need a lot of vertical space.

$this->assertSame('product', $order->activity[0]->type);
$this->assertSame('created', $order->activity[0]->reason);
$this->assertSame(100_00, $order->activity[0]->price);
$this->assertSame(0_00, $order->activity[0]->paid);
 
$this->assertSame('tax', $order->activity[1]->type);
$this->assertSame('created', $order->activity[1]->reason);
$this->assertSame(5_00, $order->activity[1]->price);
$this->assertSame(0_00, $order->activity[1]->paid);
 
// …and 24 more lines

Regular assertions require you to assert each property individually. In this example, we're asserting 4 properties across 8 rows. 8 * 4 = 32 so that would require 32 separate assertions, and won't scale well. This makes it hard to see all data at a glance, and is less readable in general.

Alternatively, we could use associative arrays or tuples to assert data in bulk.

$this->assertEquals([
    ['type' => 'product', 'reason' => 'created', 'price' => 100_00, 'paid' => 0_00],
    ['type' => 'tax', 'reason' => 'created', 'price' => 5_00, 'paid' => 0_00],
    // …and 6 more lines
], $order->activity);

Associative arrays are more verbose but require a lot of repetition.

$this->assertEquals([
    ['product', 'created', 100_00, 0_00],
    ['tax', 'created', 5_00, 0_00],
    // …and 6 more lines
], $order->activity);

Tuples are more compact and readable at a glance once you understand the shape. However, both suffer from whitespace issues: the columns are not aligned. We could add spaced to align them, but code style fixers don't always like this.

With tabular assertions, we get a compact, readable overview of the data, and because it's stored in a single string code style fixers won't reformat it.

$this->assertMatchesTable('
    | type        | reason   |  price |  paid  |
    | product     | created  | 100_00 |   0_00 |
    | tax         | created  |   5_00 |   0_00 |
    | tax         | created  |  10_00 |   0_00 |
    | shipping    | created  |   5_00 |   0_00 |
    | product     | paid     |   0_00 | 100_00 |
    | tax         | paid     |   0_00 |   5_00 |
    | tax         | paid     |   0_00 |  10_00 |
    | shipping    | paid     |   0_00 |   5_00 |
', $order->activity);

Failures display multiple problems

With separate expectations, tests fail on the first failed assertion which means you don't have the full picture.

$this->assertSame('product', $order->activity[0]->type);
$this->assertSame('created', $order->activity[0]->reason);
$this->assertSame(100_00, $order->activity[0]->price);
$this->assertSame(0_00, $order->activity[0]->paid);

Back to our first example of assertions, when the reason is wrong the test will fail. Did reason fail for a single row, or are the reasons wrong everywhere? This can be valuable information when debugging which is lost in classic tests.

It could also be that an activity row is missing, which causes all other rows to fail. This doesn't mean they contain wrong data, the assertions are tied to a different index. Tabular testing makes this clear with a diff.

Screenshot of a tabular assertion diff in PhpStorm

Dynamic placeholders

Sometimes you want to compare data without actually comparing the exact value. For example, you want to assert that each person is in the same team, but don't know the team ID because the data is randomly seeded on every run.

With tabular assertions, you can mark a column as dynamic by prefixing a #. This will assign each unique value to a placeholder ID, so similar values can be compared.

In our initial example, we don't care about the exact product_id of the rows as it's a randomly seeded ID we can't assert. We do however care that the created and paid activity are tied to the same product, which becomes clear with the placeholders.

$this->assertMatchesTable('
    | type        | reason   | #product_id | #tax_id | #shipping_id | #payment_id |  price |  paid  |
    | product     | created  |          #1 |         |              |             | 100_00 |   0_00 |
    | tax         | created  |             |      #1 |              |             |   5_00 |   0_00 |
    | tax         | created  |             |      #2 |              |             |  10_00 |   0_00 |
    | shipping    | created  |             |         |           #1 |             |   5_00 |   0_00 |
    | product     | paid     |          #1 |         |              |          #1 |   0_00 | 100_00 |
    | tax         | paid     |             |      #1 |              |          #1 |   0_00 |   5_00 |
    | tax         | paid     |             |      #2 |              |          #1 |   0_00 |  10_00 |
    | shipping    | paid     |             |         |           #1 |          #1 |   0_00 |   5_00 |
', $order->activity);

Setting up tabular assertions with PHPUnit

Tabular assertions can be installed via composer.

composer require spatie/tabular-assertions --dev

Next, add the TabularAssertions trait to your test case (or a base test case if you want to enable it everywhere.)

use PHPUnit\Framework\TestCase;
use Spatie\TabularAssertions\PHPUnit\TabularAssertions;
 
class OrderLogTest extends TestCase
{
    use TabularAssertions;
}

Finally, assert data with the assertMatchesTable method.

use PHPUnit\Framework\TestCase;
use Spatie\TabularAssertions\PHPUnit\TabularAssertions;
 
class OrderLogTest extends TestCase
{
    use TabularAssertions;
 
    public function test_it_logs_order_activity(): void
    {
        $order = OrderFactory::create()
            ->withPrice(100_00)
            ->withTaxRates([5_00, 10_00])
            ->withShipping(5_00)
            ->paid();
 
        $this->assertMatchesTable('
            | type        | reason   | #product_id | #tax_id | #shipping_id | #payment_id |  price |  paid  |
            | product     | created  |          #1 |         |              |             | 100_00 |   0_00 |
            | tax         | created  |             |      #1 |              |             |   5_00 |   0_00 |
            | tax         | created  |             |      #2 |              |             |  10_00 |   0_00 |
            | shipping    | created  |             |         |           #1 |             |   5_00 |   0_00 |
            | product     | paid     |          #1 |         |              |          #1 |   0_00 | 100_00 |
            | tax         | paid     |             |      #1 |              |          #1 |   0_00 |   5_00 |
            | tax         | paid     |             |      #2 |              |          #1 |   0_00 |  10_00 |
            | shipping    | paid     |             |         |           #1 |          #1 |   0_00 |   5_00 |
        ', $order->activity);
    }
}

Custom assertions

Tabular assertions will cast the actual values to strings. We're often dealing with data more complex than stringables, in those cases it's worth creating a custom assertion method that prepares the data.

Consider the following example with a User model that has an id, name, and date_of_birth which will be cast to a Carbon object.

$this->assertMatchesTable('
    | name       |       date_of_birth |
    | Sebastian  | 1992-02-01 00:00:00 |
', User::all());

Because Carbon objects automatically append seconds when stringified, our table becomes noisy. Instead, we'll create a custom assertMatchesUsers assertion to prepare our data before asserting.

class UserTest extends TestCase
{
    use TabularAssertions;
 
    public function test_it_has_users(): void
    {
        $this->assertMatchesUsers('
            | name       | date_of_birth |
            | Sebastian  |    1992-02-01 |
        ', User::all());
    }
 
    private function assertMatchesUsers(string $expected, Collection $users): void
    {
        $users = $users->map(function (User $user) {
            return [
                'name' => $user->name,
                'date_of_birth' => $user->date_of_birth->format('Y-m-d'),
            ];
        });
 
        $this->assertMatchesTable($expected, $users);
    }
}

This can also useful for any data transformations or truncations you want to do before asserting. Another example: first_name and last_name might be separate columns in the database, but in assertions they can be combined to reduce unnecessary whitespace in the table.

class UserTest extends TestCase
{
    use TabularAssertions;
 
    public function test_it_has_users(): void
    {
        $this->assertMatchesUsers('
            | name                | date_of_birth |
            | Sebastian De Deyne  |    1992-02-01 |
        ', User::all());
    }
 
    private function assertMatchesUsers(string $expected, Collection $users): void
    {
        $users = $users->map(function (User $user) {
            return [
                'name' => $user->first_name . ' ' . $user->last_name,
                'date_of_birth' => $user->date_of_birth->format('Y-m-d'),
            ];
        });
 
        $this->assertMatchesTable($expected, $users);
    }
}

The full source & documentation for spatie/tabular-assertions is available on GitHub.