lelinea/api-snapshot-testing

Provides PHPUnit assertions for api snapshot testing

v1.6.1 2024-12-12 11:26 UTC

Requires

• php: >=8.1
• ext-dom: *
• ext-json: *
• ext-mbstring: *
• ext-simplexml: *
• phpunit/phpunit: ~9.1
• symfony/filesystem: 6.4.*
• symfony/property-access: 6.4.*
• webmozart/assert: ~1.2

Requires (Dev)

• friendsofphp/php-cs-fixer: ~3.14
• phpstan/phpstan: ~1.12
• phpstan/phpstan-strict-rules: ~1.6
• slevomat/coding-standard: ~6.4
• squizlabs/php_codesniffer: ~3.7

MIT

README

Provides PHPUnit assertions for snapshot testing

Installation

composer require --dev lelinea/snapshot-testing

Basic Usage

use Lelinea\ApiSnapshotTesting\MatchesSnapshots;

final class MyUnitTest extends TestCase
{
    use MatchesSnapshots;
    
    public function testJson()
    {
        $myJsonData = json_encode([
            'foo' => 'bar',
        ]);
        
        $this->assertMatchesJsonSnapshot($myJsonData, 'localhost/json-test-route');
    }    
    
    public function testXml()
    {
        $myXmlData = "<?xml version="1.0" encoding="UTF-8"?><root><id>7d644cc6-70fa-11e9-89e1-220d3e3a2561</id></root>";
        
        $this->assertMatchesXmlSnapshot($myXmlData, 'localhost/xml-test-route');
    } 
    
    public function testCsv()
    {
        $myCsvData = <<<CSV
"foo bar";123
"foo bar";456
"foo bar";789
CSV;
        $this->assertMatchesCsvSnapshot($myCsvData);
    }    
    
    public function testCsvVariant()
    {
        $myCsvData = <<<CSV
'foo bar',123
'foo bar',456
'foo bar',789
CSV;
        $this->assertMatchesCsvSnapshot($myCsvData, [], false, ',', "'");
}

Using Wildcards

If you have content in your data which changes intentionally you can use wildcards:

use Lelinea\ApiSnapshotTesting\MatchesSnapshots;
use Lelinea\ApiSnapshotTesting\Wildcard\UuidWildcard;

final class MyUnitTest extends TestCase
{
    use MatchesSnapshots;
    
    public function testJson()
    {
        $myJsonData = json_encode([
            'id' => '7d644cc6-70fa-11e9-89e1-220d3e3a2561',
            'foo' => 'bar',
        ]);
        
        $this->assertMatchesJsonSnapshot($myJsonData, 'localhost/json-test-route', [
            new UuidWildcard('id'),
        ]);
    }    
    
    public function testXml()
    {
        $myXmlData = '<?xml version="1.0" encoding="UTF-8"?><root><id>7d644cc6-70fa-11e9-89e1-220d3e3a2561</id></root>';

        $this->assertMatchesXmlSnapshot($myXmlData, 'localhost/xml-test-route', [
            new UuidWildcard('id'),
        ]);
    }
}

This ignores the concrete uuid given for the field "id" and only checks that a valid uuid is provided.

The library currently supports the following wildcards:

• BooleanWildcard
• IntegerWildcard
• UuidWildcard
• UuidOrNullWildcard
• DateTimeWildcard
• DateTimeOrNullWildcard
• StringWildcard
• StringOrNullWildcard

Usage in CI

When running your tests in Continuous Integration you would possibly want to disable the creation of snapshots.

By using the --without-creating-snapshots parameter, PHPUnit will fail if the snapshots don't exist.

> ./vendor/bin/phpunit -d --without-creating-snapshots

1) ExampleTest::test_it_matches_a_string
Snapshot "ExampleTest__test_it_matches_a_string__1.txt" does not exist. 
You can automatically create it by removing `-d --without-creating-snapshots` of PHPUnit's CLI arguments.