Readme

Author: sebastiandedeyne

README.md

@@ -1,11 +1,65 @@
-# This is my package tabular-assertions
+# Write tabular assertions with Pest or PHPUnit
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/tabular-assertions.svg?style=flat-square)](https://packagist.org/packages/spatie/tabular-assertions)
 [![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/spatie/tabular-assertions/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/spatie/tabular-assertions/actions?query=workflow%3Arun-tests+branch%3Amain)
 [![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/spatie/tabular-assertions/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/spatie/tabular-assertions/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
 [![Total Downloads](https://img.shields.io/packagist/dt/spatie/tabular-assertions.svg?style=flat-square)](https://packagist.org/packages/spatie/tabular-assertions)
 
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+**🚧 This package is under development! Documentation is scarce and it isn't published on Packagist yet but feel free to play around already.** 
+
+Tabular 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. 
+
+With Pest:
+
+```php
+$users = [
+    ['id' => 20, 'name' => 'John Doe', 'email' => 'john@doe.com'],
+    ['id' => 1245, 'name' => 'Jane Doe', 'email' => 'jane@doe.com'],
+];
+
+test('it compares a table', function () use ($users) {
+    $order = Order::factory()
+        ->addItem('Pen', 2)
+        ->addItem('Paper', 1)
+        ->addItem('Pencil', 5)
+        ->create();
+
+    expect($order->items)->toMatchTable('
+        | #id | #order_id | name   | quantity |
+        |  #1 |        #1 | Pen    |        2 |
+        |  #2 |        #1 | Paper  |        1 |
+        |  #3 |        #1 | Pencil |        5 |
+    ');
+});
+```
+
+With PHPUnit:
+
+```php
+use PHPUnit\Framework\TestCase;
+use Spatie\TabularAssertions\PHPUnit\TabularAssertions;
+
+class PHPUnitTest extends TestCase
+{
+    use TabularAssertions;
+
+    public function test_it_contains_users(): void
+    {
+        $order = Order::factory()
+            ->addItem('Pen', 2)
+            ->addItem('Paper', 1)
+            ->addItem('Pencil', 5)
+            ->create();
+    
+        $this->assertMatchesTable('
+            | #id | #order_id | name   | quantity |
+            |  #1 |        #1 | Pen    |        2 |
+            |  #2 |        #1 | Paper  |        1 |
+            |  #3 |        #1 | Pencil |        5 |
+        ', $order->items);
+    }
+}
+```
 
 ## Support us
 
@@ -23,45 +77,43 @@ You can install the package via composer:
 composer require spatie/tabular-assertions
 ```
 
-You can publish and run the migrations with:
-
-```bash
-php artisan vendor:publish --tag="tabular-assertions-migrations"
-php artisan migrate
-```
+## Usage
 
-You can publish the config file with:
+### Basic usage: Pest
 
-```bash
-php artisan vendor:publish --tag="tabular-assertions-config"
-```
+With Pest, the plugin will be autoloaded and readily available. Use the custom `toMatchTable()` expectation to compare data with a table.
 
-This is the contents of the published config file:
+### Basic usage: PHPUnit
 
-```php
-return [
-];
-```
+With PHPUnit, add the `Spatie\TabularAssertions\PHPUnit\TabularAssertions` trait to the tests you want to use tabular assertions with. Use `$this->assertMatchesTable()` to compare data with a table. 
 
-Optionally, you can publish the views using
+### Dynamic values
 
-```bash
-php artisan vendor:publish --tag="tabular-assertions-views"
-```
+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. 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.
 
-## Usage
+For example, Sebastian & Freek are in team Spatie which has a random ID, and Christoph is in team Laravel with another random ID.
 
-```php
-$tabularAssertions = new Spatie\TabularAssertions();
-echo $tabularAssertions->echoPhrase('Hello, Spatie!');
+```
+| name      | #team_id |
+| Sebastian |       #1 |
+| Freek     |       #1 |
+| Christoph |       #2 |
 ```
 
 ## Testing
 
+Tests are written with Pest. You can either use Pest's CLI or run `composer test` to run the suite.
+
 ```bash
 composer test
 ```
 
+In addition to tests, PhpStan statically analyses the code. Use `composer analyse` to run PhpStan. 
+
+```bash
+composer analyse
+```
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "spatie/tabular-assertions",
-    "description": "This is my package tabular-assertions",
+    "description": "Write tabular assertions with Pest or PHPUnit",
     "keywords": [
         "spatie",
         "tabular-assertions"
@@ -21,12 +21,12 @@
         "laravel/pint": "^1.0",
         "pestphp/pest": "^2.28",
         "phpstan/phpstan": "^1.10",
+        "phpunit/phpunit": "^10.5",
         "spatie/ray": "^1.40"
     },
     "autoload": {
         "psr-4": {
-            "Spatie\\TabularAssertions\\": "src/",
-            "Spatie\\TabularAssertions\\Database\\Factories\\": "database/factories/"
+            "Spatie\\TabularAssertions\\": "src/"
         },
         "files": ["src/Pest/Autoload.php"]
     },
@@ -37,6 +37,7 @@
     },
     "scripts": {
         "test": "vendor/bin/pest",
+        "analyse": "vendor/bin/phpstan",
         "format": "vendor/bin/pint"
     },
     "config": {

tests/Integration/PHPUnitTest.php

@@ -11,13 +11,15 @@ class PHPUnitTest extends TestCase
 
     public function test_it_compares_a_table(): void
     {
+        $users = [
+            ['id' => 20, 'name' => 'John Doe', 'email' => 'john@doe.com'],
+            ['id' => 1245, 'name' => 'Jane Doe', 'email' => 'jane@doe.com'],
+        ];
+
         $this->assertMatchesTable('
             |   id | name        | email           |
             |   20 | John Doe    | john@doe.com    |
             | 1245 | Jane Doe    | jane@doe.com    |
-        ', [
-            ['id' => 20, 'name' => 'John Doe', 'email' => 'john@doe.com'],
-            ['id' => 1245, 'name' => 'Jane Doe', 'email' => 'jane@doe.com'],
-        ]);
+        ', $users);
     }
 }