Merge pull request #175 from spatie/image-assertions

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

@@ -15,7 +15,7 @@ public function serialize($data): string
             throw new CantBeSerialized('Only strings can be serialized to html');
         }
 
-        if ('' === $data) {
+        if ($data === '') {
             return "\n";
         }
 

src/Drivers/HtmlDriver.php

@@ -0,0 +1,51 @@
+<?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;
@@ -111,6 +112,17 @@ 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

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),
+        );
+    }
+}