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 Pest.

Read more

Today I tagged v1 of a new testing package: spatie/tabular-assertions. It's a distillation of a testing method I've been using in client projects the past two years. The package supports both PHPUnit and Pest out of the box.

With tabular assertions, you describe the expected outcome in a markdown-like table format.

expect($order->logs)->toLookLike("
    | type        | reason   | price | paid  |
    | product     | created  | 80_00 | 80_00 |
    | tax         | created  |  5_00 |  5_00 |
    | tax         | created  | 10_00 | 10_00 |
    | shipping    | created  |  5_00 |  5_00 |
    | product     | paid     |  0_00 |  0_00 |
    | tax         | paid     |  0_00 |  0_00 |
    | tax         | paid     |  0_00 |  0_00 |
    | shipping    | paid     |  0_00 |  0_00 |
");

Tabular assertions have two major benefits over other testing strategies: expectations are optimized for readability & failed assertions can display multiple errors at once.

For an in-depth introduction to tabular testing, I've written two separate guides for Pest & PHPUnit.

• Tabular assertions with Pest
• Tabular assertions with PHPUnit

Inspiration

I haven't come across this exact method anywhere else, so I had to come up with a name. If there's prior art that matches this with a better name, I'd love to know!

The idea was inspired by Jest, which allows you to use a table as a data provider.

Snapshot testing is also closely related to this. But snapshots aren't always optimized for readability, are stored in a separate file (not alongside the test), and are hard to write by hand (no TDD).

Tabular assertions have been a huge help when comparing large, ordered data sets like financial data or a time series. I hope you find it useful too!