add image assertions

Author: freekmurze

README.md

@@ -97,6 +97,7 @@ To make snapshot assertions, use the `Spatie\Snapshots\MatchesSnapshots` trait i
 - `assertMatchesTextSnapshot($actual)`
 - `assertMatchesXmlSnapshot($actual)`
 - `assertMatchesYamlSnapshot($actual)`
+- `assertMachesImageSnapshot($actual)`
 
 ### Snapshot Testing 101
 
@@ -180,6 +181,17 @@ The `assertMatchesFileHashSnapshot($filePath)` assertion asserts that the hash o
 
 The `assertMatchesFileSnapshot($filePath)` assertion works almost the same way as the file hash assertion, except that it actually saves the whole file in the snapshots directory. If the assertion fails, it places the failed file next to the snapshot file so they can easily be manually compared. The persisted failed file is automatically deleted when the test passes. This assertion is most useful when working with binary files that should be manually compared like images or pdfs.
 
+### Image snapshots
+
+The `assertImageSnapshot` requires the [spatie/pixelmatch-php](https://github.com/spatie/pixelmatch-php) package to be installed.
+
+This assertion will pass if the given image is nearly identical to the snapshot that was made the first time the test was run. You can customize the threshold by passing a second argument to the assertion. Higher values will make the comparison more sensitive. The threshold should be between 0 and 1.
+
+```php 
+$this->assertMatchesImageSnapshot($imagePath, 0.1);
+```
+
+
 ### Customizing Snapshot Ids and Directories
 
 Snapshot ids are generated via the `getSnapshotId` method on the `MatchesSnapshot` trait. Override the method to customize the id. By default, a snapshot id exists of the test name, the test case name and an incrementing value, e.g. `Test__my_test_case__1`.

build/report.junit.xml

@@ -30,6 +30,10 @@
         "symfony/serializer": "^5.2|^6.2",
         "symfony/yaml": "^5.2|^6.2"
     },
+    "require-dev": {
+        "spatie/pixelmatch-php": "dev-main",
+        "spatie/ray": "^1.37"
+    },
     "autoload": {
         "psr-4": {
             "Spatie\\Snapshots\\": "src"
@@ -53,4 +57,5 @@
             "dev-v5": "5.0-dev"
         }
     }
+
 }

composer.json

@@ -0,0 +1,53 @@
+<?php
+
+namespace Spatie\Snapshots\Drivers;
+
+use PHPUnit\Framework\Assert;
+use PHPUnit\Framework\ExpectationFailedException;
+use Spatie\Pixelmatch\Exceptions\CouldNotCompare;
+use Spatie\Pixelmatch\Pixelmatch;
+use Spatie\Snapshots\Driver;
+
+class ImageDriver implements Driver
+{
+    public function __construct(
+        protected float $threshold = 0.1,
+        protected bool $includeAa = true,
+    )
+    {
+    }
+
+    public function serialize($data): string
+    {
+        return file_get_contents($data);
+    }
+
+    public function extension(): string
+    {
+        return 'png';
+    }
+
+    public function match($expected, $actual)
+    {
+        $tempPath = sys_get_temp_dir();
+
+        $expectedTempPath = $tempPath . '/expected.png';
+        file_put_contents($expectedTempPath, $expected);
+
+        $actualTempPath = $tempPath . '/actual.png';
+        file_put_contents($actualTempPath, $actual);
+
+        $pixelMatch = Pixelmatch::new($expectedTempPath, $actualTempPath)
+            ->threshold($this->threshold)
+            ->includeAa($this->includeAa);
+
+        try {
+            $result = $pixelMatch->matches();
+        } catch (CouldNotCompare $exception) {
+            throw new
+            ExpectationFailedException($exception->getMessage());
+        }
+
+        Assert::assertTrue($result);
+    }
+}

src/Drivers/ImageDriver.php

@@ -7,6 +7,7 @@
 use Spatie\Snapshots\Concerns\SnapshotDirectoryAware;
 use Spatie\Snapshots\Concerns\SnapshotIdAware;
 use Spatie\Snapshots\Drivers\HtmlDriver;
+use Spatie\Snapshots\Drivers\ImageDriver;
 use Spatie\Snapshots\Drivers\JsonDriver;
 use Spatie\Snapshots\Drivers\ObjectDriver;
 use Spatie\Snapshots\Drivers\TextDriver;
@@ -50,7 +51,7 @@ public function markTestIncompleteIfSnapshotsHaveChanged()
 
     public function assertMatchesSnapshot($actual, Driver $driver = null): void
     {
-        if (! is_null($driver)) {
+        if (!is_null($driver)) {
             $this->doSnapshotAssertion($actual, $driver);
 
             return;
@@ -67,7 +68,7 @@ public function assertMatchesSnapshot($actual, Driver $driver = null): void
 
     public function assertMatchesFileHashSnapshot(string $filePath): void
     {
-        if (! file_exists($filePath)) {
+        if (!file_exists($filePath)) {
             $this->fail('File does not exist');
         }
 
@@ -111,15 +112,27 @@ public function assertMatchesYamlSnapshot($actual): void
         $this->assertMatchesSnapshot($actual, new YamlDriver());
     }
 
+    public function assertMatchesImageSnapshot(
+        $actual,
+        float $threshold = 0.1,
+        bool $includeAa = true
+    ): void
+    {
+        $this->assertMatchesSnapshot($actual, new ImageDriver(
+            $threshold,
+            $includeAa,
+        ));
+    }
+
     /*
      * Determines the directory where file snapshots are stored. By default a
      * `__snapshots__/files` directory is created at the same level as the
      * test class.
      */
     protected function getFileSnapshotDirectory(): string
     {
-        return $this->getSnapshotDirectory().
-            DIRECTORY_SEPARATOR.
+        return $this->getSnapshotDirectory() .
+            DIRECTORY_SEPARATOR .
             'files';
     }
 
@@ -148,7 +161,7 @@ protected function shouldUpdateSnapshots(): bool
      */
     protected function shouldCreateSnapshots(): bool
     {
-        return ! in_array('--without-creating-snapshots', $_SERVER['argv'], true)
+        return !in_array('--without-creating-snapshots', $_SERVER['argv'], true)
             && getenv('CREATE_SNAPSHOTS') !== 'false';
     }
 
@@ -162,7 +175,7 @@ protected function doSnapshotAssertion(mixed $actual, Driver $driver)
             $driver
         );
 
-        if (! $snapshot->exists()) {
+        if (!$snapshot->exists()) {
             $this->assertSnapshotShouldBeCreated($snapshot->filename());
 
             $this->createSnapshotAndMarkTestIncomplete($snapshot, $actual);
@@ -190,7 +203,7 @@ protected function doSnapshotAssertion(mixed $actual, Driver $driver)
 
     protected function doFileSnapshotAssertion(string $filePath): void
     {
-        if (! file_exists($filePath)) {
+        if (!file_exists($filePath)) {
             $this->fail('File does not exist');
         }
 
@@ -204,7 +217,7 @@ protected function doFileSnapshotAssertion(string $filePath): void
 
         $this->snapshotIncrementor++;
 
-        $snapshotId = $this->getSnapshotId().'.'.$fileExtension;
+        $snapshotId = $this->getSnapshotId() . '.' . $fileExtension;
         $snapshotId = Filename::cleanFilename($snapshotId);
 
         // If $filePath has a different file extension than the snapshot, the test should fail
@@ -227,13 +240,13 @@ protected function doFileSnapshotAssertion(string $filePath): void
             $this->fail("File did not match the snapshot file extension (expected: {$expectedExtension}, was: {$fileExtension})");
         }
 
-        $failedSnapshotId = $snapshotId.'_failed.'.$fileExtension;
+        $failedSnapshotId = $snapshotId . '_failed.' . $fileExtension;
 
         if ($fileSystem->has($failedSnapshotId)) {
             $fileSystem->delete($failedSnapshotId);
         }
 
-        if (! $fileSystem->has($snapshotId)) {
+        if (!$fileSystem->has($snapshotId)) {
             $this->assertSnapshotShouldBeCreated($failedSnapshotId);
 
             $fileSystem->copy($filePath, $snapshotId);
@@ -243,7 +256,7 @@ protected function doFileSnapshotAssertion(string $filePath): void
             return;
         }
 
-        if (! $fileSystem->fileEquals($filePath, $snapshotId)) {
+        if (!$fileSystem->fileEquals($filePath, $snapshotId)) {
             if ($this->shouldUpdateSnapshots()) {
                 $fileSystem->copy($filePath, $snapshotId);
 
@@ -276,8 +289,8 @@ protected function updateSnapshotAndMarkTestIncomplete(Snapshot $snapshot, $actu
 
     protected function rethrowExpectationFailedExceptionWithUpdateSnapshotsPrompt($exception): void
     {
-        $newMessage = $exception->getMessage()."\n\n".
-            'Snapshots can be updated by passing '.
+        $newMessage = $exception->getMessage() . "\n\n" .
+            'Snapshots can be updated by passing ' .
             '`-d --update-snapshots` through PHPUnit\'s CLI arguments.';
 
         $exceptionReflection = new ReflectionObject($exception);
@@ -301,9 +314,9 @@ protected function assertSnapshotShouldBeCreated(string $snapshotFileName): void
         }
 
         $this->fail(
-            "Snapshot \"$snapshotFileName\" does not exist.\n".
-            'You can automatically create it by removing '.
-            'the `CREATE_SNAPSHOTS=false` env var, or '.
+            "Snapshot \"$snapshotFileName\" does not exist.\n" .
+            'You can automatically create it by removing ' .
+            'the `CREATE_SNAPSHOTS=false` env var, or ' .
             '`-d --without-creating-snapshots` of PHPUnit\'s CLI arguments.'
         );
     }

src/MatchesSnapshots.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace Spatie\Snapshots\Test\Unit\Drivers;
+
+use PHPUnit\Framework\ExpectationFailedException;
+use PHPUnit\Framework\TestCase;
+use Spatie\Snapshots\Drivers\ImageDriver;
+
+class ImageDriverTest extends TestCase
+{
+    public function setUp(): void
+    {
+        parent::setUp();
+
+        $this->driver = new ImageDriver();
+
+        $this->pathToImageA = __DIR__ . '/../test_files/testA.png';
+        $this->pathToImageB = __DIR__ . '/../test_files/testB.png';
+        $this->pathToImageWithDifferentDimensions = __DIR__ . '/../test_files/testC.png';
+
+    }
+
+    /** @test */
+    public function it_can_serialize_an_image()
+    {
+        $data = $this->driver->serialize($this->pathToImageA);
+
+        $this->assertEquals($data, file_get_contents($this->pathToImageA));
+    }
+
+    /** @test */
+    public function it_can_determine_that_two_images_are_the_same()
+    {
+        $this->driver->match(
+            file_get_contents($this->pathToImageA),
+            file_get_contents($this->pathToImageA),
+        );
+
+        $this->doesNotPerformAssertions();
+    }
+
+    /** @test */
+    public function it_can_determine_that_two_images_are_not_same()
+    {
+        $this->expectException(ExpectationFailedException::class);
+
+        $this->driver->match(
+            file_get_contents($this->pathToImageA),
+            file_get_contents($this->pathToImageB),
+        );
+    }
+
+    /** @test */
+    public function it_will_determine_that_two_images_with_different_dimensions_are_different()
+    {
+        $this->expectException(ExpectationFailedException::class);
+
+        $this->driver->match(
+            file_get_contents($this->pathToImageA),
+            file_get_contents($this->pathToImageWithDifferentDimensions),
+        );
+    }
+}