Introducing tabular assertions

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.

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

Screenshot of a tabular assertion diff in PhpStorm

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


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!

Is snapshot testing viable in PHP?

Christopher Pitt wrote a pretty comprehensive article on one of our latest packages, which is one of my favorite packages I've written at Spatie to date, phpunit-snapshot-assertions.

Ah-ha moments are beautiful and rare in programming. Every so often, we’re fortunate enough to discover some trick or facet of a system that forever changes how we think of it. For me, that’s what snapshot testing is.

Read the full article on SitePoint, or check out phpunit-snapshot-assertions on GitHub.

A package for snapshot testing in PHPUnit

The gist of snapshot testing is asserting that a set of data hasn't changed compared to a previous version, which is a snapshot of the data, to prevent regressions. The difference between a classic and an is that you don't write the expectation yourself when snapshot testing.

When a snapshot assertion happens for the first time, it creates a snapshot file with the actual output, and marks the test as incomplete. Every subsequent run will compare the output with the existing snapshot file to check for regressions.

Snapshot testing is most useful larger datasets that can change over time, like serializing an object for an XML export or a JSON API endpoint.

Read more