{"id":15014421,"url":"https://github.com/spatie/tabular-assertions","last_synced_at":"2025-04-05T05:03:51.174Z","repository":{"id":214674615,"uuid":"720153999","full_name":"spatie/tabular-assertions","owner":"spatie","description":"Write tabular assertions with Pest or PHPUnit","archived":false,"fork":false,"pushed_at":"2025-02-03T18:06:32.000Z","size":48,"stargazers_count":54,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-29T04:04:41.230Z","etag":null,"topics":["pest","php","phpunit","testing"],"latest_commit_sha":null,"homepage":"https://spatie.be/open-source","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-11-17T17:37:02.000Z","updated_at":"2025-02-03T18:06:28.000Z","dependencies_parsed_at":"2023-12-29T21:54:09.066Z","dependency_job_id":"1375c86c-df74-4d62-9d67-fbfd8eb4ccc9","html_url":"https://github.com/spatie/tabular-assertions","commit_stats":null,"previous_names":["spatie/tabular-assertions"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftabular-assertions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftabular-assertions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftabular-assertions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Ftabular-assertions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/tabular-assertions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289409,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pest","php","phpunit","testing"],"created_at":"2024-09-24T19:45:36.314Z","updated_at":"2025-04-05T05:03:51.156Z","avatar_url":"https://github.com/spatie.png","language":"PHP","readme":"# Write tabular assertions with Pest or PHPUnit\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/tabular-assertions.svg?style=flat-square)](https://packagist.org/packages/spatie/tabular-assertions)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/spatie/tabular-assertions/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/spatie/tabular-assertions/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/spatie/tabular-assertions/fix-php-code-style-issues.yml?branch=main\u0026label=code%20style\u0026style=flat-square)](https://github.com/spatie/tabular-assertions/actions?query=workflow%3A\"Fix+PHP+code+style+issues\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/tabular-assertions.svg?style=flat-square)](https://packagist.org/packages/spatie/tabular-assertions)\n\nTabular assertions allow you to describe data in a Markdown table-like format and compare it to the actual data. This is especially useful when comparing large, ordered data sets like financial data or a time series. \n\nWith Pest:\n\n```php\ntest('it compares a table', function () {\n    $order = Order::factory()\n        -\u003eaddItem('Pen', 2)\n        -\u003eaddItem('Paper', 1)\n        -\u003eaddItem('Pencil', 5)\n        -\u003ecreate();\n\n    expect($order-\u003eitems)-\u003etoMatchTable('\n        | #id | #order_id | name   | quantity |\n        |  #1 |        #1 | Pen    |        2 |\n        |  #2 |        #1 | Paper  |        1 |\n        |  #3 |        #1 | Pencil |        5 |\n    ');\n});\n```\n\nWith PHPUnit:\n\n```php\nuse PHPUnit\\Framework\\TestCase;\nuse Spatie\\TabularAssertions\\PHPUnit\\TabularAssertions;\n\nclass PHPUnitTest extends TestCase\n{\n    use TabularAssertions;\n\n    public function test_it_contains_users(): void\n    {\n        $order = Order::factory()\n            -\u003eaddItem('Pen', 2)\n            -\u003eaddItem('Paper', 1)\n            -\u003eaddItem('Pencil', 5)\n            -\u003ecreate();\n\n        $this-\u003eassertMatchesTable('\n            | #id | #order_id | name   | quantity |\n            |  #1 |        #1 | Pen    |        2 |\n            |  #2 |        #1 | Paper  |        1 |\n            |  #3 |        #1 | Pencil |        5 |\n        ', $order-\u003eitems);\n    }\n}\n```\n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/tabular-assertions.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/tabular-assertions)\n\nWe invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).\n\nWe highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require spatie/tabular-assertions\n```\n\n## Why tabular assertions?\n\nTabular assertions have two major benefits over other testing strategies: expectations are optimized for readability \u0026 failed assertions can display multiple errors at once.\n\n**1. You can hand-write expectations that contain a lot of data and are optimized for readability.** Text-based tables are compact, allow you to compare the data in two dimensions.\n\nThe alternative would be to write multiple assertions.\n\n```php\nexpect($items[0]['order_id'])-\u003etoBe($order-\u003eid);\nexpect($items[0]['name'])-\u003etoBeDate('Pen');\nexpect($items[0]['quantity'])-\u003etoBe(2);\n\nexpect($items[1]['order_id'])-\u003etoBe($order-\u003eid);\nexpect($items[1]['name'])-\u003etoBeDate('Paper');\nexpect($items[1]['quantity'])-\u003etoBe(1);\n\n// …\n```\n\nExpectations require you to assert each property individually. This makes it hard to see all dates at a glance, and is less readable in general.\n\nAssociative arrays require a lot of repetition with labels.\n\n```php\nexpect($items[0])-\u003etoBe([\n    'order_id' =\u003e $order-\u003eid,\n    'name' =\u003e 'Pen',\n    'quantity' =\u003e 2,\n]);\n\nexpect($items[1])-\u003etoBe([\n    'order_id' =\u003e $order-\u003eid,\n    'date' =\u003e 'Paper',\n    'quantity' =\u003e 1,\n]);\n\n// …\n```\n\nArrays without keys can't be aligned properly (manually maintained spaces would be striped by code style fixers). This becomes unclear when asserting multiple columns with different lengths.\n\n```php\nexpect($items)-\u003etoBe([\n    [$order-\u003eid, 'Pen', 2],\n    [$order-\u003eid, 'Paper', 1],\n    // …\n]);\n```\n\nWith 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.\n\n```php\nexpect($items)-\u003etoMatchTable('\n    | #id | #order_id | name   | quantity |\n    |  #1 |        #1 | Pen    |        2 |\n    |  #2 |        #1 | Paper  |        1 |\n    |  #3 |        #1 | Pencil |        5 |\n');\n```\n\n**2. Errors that can display multiple problems.** With separate expectations, tests fail on the first failed assertion which means you don't have the full picture (small issue vs. everything broken)\n\nIf you serialize two datasets to a table, you can get a nice output in a visual diff like PhpStorm's output when you use `assertEquals`.\n\nIn this assertions, you can see one value is wrong and one row is missing in one glance. With separate assertions, you only see the first error your test runner comes across.\n\n\u003cimg width=\"698\" alt=\"CleanShot 2023-02-09 at 14 48 38@2x\" src=\"https://user-images.githubusercontent.com/1561079/217830800-e88953a5-446b-49d1-be7d-edfbb5484441.png\"\u003e\n\nThis style of testing really shines when you have a lot of data to assert. This example has 9 rows and 9 columns, which means we're comparing 81 data points while keeping it all readable.\n\n```php\nexpect($order-\u003elogs)-\u003etoLookLike(\"\n    | type        | reason   | #product_id | #tax_id | #shipping_id | #payment_id | price | paid  | refunded |\n    | product     | created  |       #1    |         |              |             | 80_00 | 80_00 |     0_00 |\n    | tax         | created  |       #1    |      #1 |              |             |  5_00 |  5_00 |     0_00 |\n    | tax         | created  |       #1    |      #2 |              |             | 10_00 | 10_00 |     0_00 |\n    | shipping    | created  |       #1    |         |           #1 |             |  5_00 |  5_00 |     0_00 |\n    | product     | paid     |       #1    |         |              |          #1 |  0_00 |  0_00 |     2_00 |\n    | tax         | paid     |       #1    |      #1 |              |          #1 |  0_00 |  0_00 |     0_00 |\n    | tax         | paid     |       #1    |      #2 |              |          #1 |  0_00 |  0_00 |     0_00 |\n    | shipping    | paid     |       #1    |         |           #1 |          #1 |  0_00 |  0_00 |     0_00 |\n\");\n```\n\n## Usage\n\n### Basic usage: Pest\n\nWith Pest, the plugin will be autoloaded and readily available. Use the custom `toMatchTable()` expectation to compare data with a table.\n\n### Basic usage: PHPUnit\n\nWith PHPUnit, add the `Spatie\\TabularAssertions\\PHPUnit\\TabularAssertions` trait to the tests you want to use tabular assertions with. Use `$this-\u003eassertMatchesTable()` to compare data with a table. \n\n### Dynamic values\n\nSometimes 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. A column can be marked as \"dynamic\" by prefixing its name with a `#`. Dynamic columns will replace values with placeholders. A placeholder is unique for the value in the column. So a team with ID `123` would always be rendered as `#1`, another team `456` with `#2` etc.\n\nFor example, Sebastian \u0026 Freek are in team Spatie which has a random ID, and Christoph is in team Laravel with another random ID.\n\n```\n| name      | #team_id |\n| Sebastian |       #1 |\n| Freek     |       #1 |\n| Christoph |       #2 |\n```\n\n### Custom assertions\n\nTabular 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.\n\nConsider the following example with a `User` model that has an `id`, `name`, and `date_of_birth` which will be cast to a `Carbon` object.\n\n```php\nexpect(User::all())-\u003etoMatchTable('\n    | id | name       |       date_of_birth |\n    |  1 | Sebastian  | 1992-02-01 00:00:00 |\n');\n```\n\nBecause `Carbon` objects automatically append seconds when stringified, our table becomes noisy. Instead, we'll create a custom `toMatchUsers` assertion to prepare our data before asserting.\n\n```php\nexpect()-\u003eextend('toMatchUsers', function (string $expected) {\n    $users = $this-\u003evalue-\u003emap(function (User $user) {\n        return [\n            'id' =\u003e $user-\u003eid,\n            'name' =\u003e $user-\u003ename,\n            'date_of_birth' =\u003e $user-\u003edate_of_birth-\u003eformat('Y-m-d'),\n        ];\n    });\n\n    expect($users)-\u003etoBe($expected);\n});\n```\n\n```php\nexpect(User::all())-\u003etoMatchTable('\n    | id | name       | date_of_birth |\n    |  1 | Sebastian  |    1992-02-01 |\n');\n```\n\nIn PHPUnit, this would be a custom assertion method.\n\n```php\nclass UserTest extends TestCase\n{\n    use TabularAssertions;\n\n    private function assertMatchesUsers(string $expected, Collection $users): void\n    {\n        $users = $users-\u003emap(function (User $user) {\n            return [\n                'id' =\u003e $user-\u003eid,\n                'name' =\u003e $user-\u003ename,\n                'date_of_birth' =\u003e $user-\u003edate_of_birth-\u003eformat('Y-m-d'),\n            ];\n        });\n\n        $this-\u003eassertMatchesTable($expected, $users);\n    }\n}\n```\n\nThis 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.\n\n```php\nexpect(User::all())-\u003etoMatchTable('\n    | id | name                | date_of_birth |\n    |  1 | Sebastian De Deyne  |    1992-02-01 |\n');\n```\n\n```php\nexpect()-\u003eextend('toMatchUsers', function (string $expected) {\n    $users = $this-\u003evalue-\u003emap(function (User $user) {\n        return [\n            'id' =\u003e $user-\u003eid,\n            'name' =\u003e $user-\u003efirst_name . ' ' . $user-\u003elast_name,\n            'date_of_birth' =\u003e $user-\u003edate_of_birth-\u003eformat('Y-m-d'),\n        ];\n    });\n\n    expect($users)-\u003etoBe($expected);\n});\n```\n\n## Inspiration \u0026 alternatives\n\nThe idea for this was inspired by Jest, which allows you to use a [table as a data provider](https://dev.to/andrewmcoupe/sit-down-at-my-jest-tagged-template-literal-table-and-tidy-up-your-tests-4f71).\n\n[Snapshot testing](https://github.com/spatie/phpunit-snapshot-assertions) 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).\n\n## Testing\n\nTests are written with Pest. You can either use Pest's CLI or run `composer test` to run the suite.\n\n```bash\ncomposer test\n```\n\nIn addition to tests, PhpStan statically analyses the code. Use `composer analyse` to run PhpStan. \n\n```bash\ncomposer analyse\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Sebastian De Deyne](https://github.com/sebastiandedeyne)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Ftabular-assertions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Ftabular-assertions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Ftabular-assertions/lists"}