add file snapshot assertion

Author: SjorsO

README.md

@@ -78,11 +78,12 @@ composer require spatie/phpunit-snapshot-assertions
 
 ## Usage
 
-To make snapshot assertions, use the `Spatie\Snapshots\MatchesSnapshots` trait in your test case class. This adds four assertion methods to the class:
+To make snapshot assertions, use the `Spatie\Snapshots\MatchesSnapshots` trait in your test case class. This adds five assertion methods to the class:
 
 - `assertMatchesSnapshot($actual)`
 - `assertMatchesJsonSnapshot($actual)`
 - `assertMatchesXmlSnapshot($actual)`
+- `assertMatchesFileSnapshot($filePath)`
 - `assertMatchesFileHashSnapshot($filePath)`
 
 ### Snapshot Testing 101
@@ -159,6 +160,13 @@ As a result, our snapshot file returns "bar" instead of "foo".
 <?php return 'bar';
 ```
 
+### File snapshots
+The `MatchesSnapshots` trait offers two ways to assert that a file is identical to the snapshot that was made the first time the test was run:
+
+The `assertMatchesFileHashSnapshot($filePath)` assertion asserts that the hash of the file passed into the function and the hash saved in the snapshot match. This assertion is fast and uses very little disk space. The downside of this assertion is that there is no easy way to see how the two files differ if the test fails. 
+    
+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.
+
 ### 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`.

src/Filesystem.php

@@ -40,4 +40,23 @@ public function put(string $filename, string $contents)
 
         file_put_contents($this->path($filename), $contents);
     }
+
+    public function delete(string $fileName)
+    {
+        return unlink($this->path($fileName));
+    }
+
+    public function copy(string $filePath, string $fileName)
+    {
+        if (! file_exists($this->basePath)) {
+            mkdir($this->basePath);
+        }
+
+        copy($filePath, $this->path($fileName));
+    }
+
+    public function fileEquals(string $filePath, string $fileName)
+    {
+        return sha1_file($filePath) === sha1_file($this->path($fileName));
+    }
 }

src/MatchesSnapshots.php

@@ -47,6 +47,11 @@ public function assertMatchesFileHashSnapshot($filePath)
         $this->assertMatchesSnapshot($actual);
     }
 
+    public function assertMatchesFileSnapshot($file)
+    {
+        $this->doFileSnapshotAssertion($file);
+    }
+
     /**
      * Determines the snapshot's id. By default, the test case's class and
      * method names are used.
@@ -74,6 +79,20 @@ protected function getSnapshotDirectory(): string
             '__snapshots__';
     }
 
+    /**
+     * Determines the directory where file snapshots are stored. By default a
+     * `__snapshots__/files` directory is created at the same level as the
+     * test class.
+     *
+     * @return string
+     */
+    protected function getFileSnapshotDirectory(): string
+    {
+        return $this->getSnapshotDirectory().
+            DIRECTORY_SEPARATOR.
+            'files';
+    }
+
     /**
      * Determines whether or not the snapshot should be updated instead of
      * matched.
@@ -124,6 +143,51 @@ protected function doSnapshotAssertion($actual, Driver $driver)
         }
     }
 
+    protected function doFileSnapshotAssertion(string $filePath)
+    {
+        if (! file_exists($filePath)) {
+            $this->fail('File does not exist');
+        }
+
+        $fileExtension = pathinfo($filePath, PATHINFO_EXTENSION);
+
+        if (empty($fileExtension)) {
+            $this->fail("Unable to make a file snapshot, file does not have a file extension ({$filePath})");
+        }
+
+        $fileSystem = Filesystem::inDirectory($this->getFileSnapshotDirectory());
+
+        $this->snapshotIncrementor++;
+
+        $snapshotId = $this->getSnapshotId().'.'.$fileExtension;
+
+        $failedSnapshotId = $snapshotId.'_failed.'.$fileExtension;
+
+        if ($fileSystem->has($failedSnapshotId)) {
+            $fileSystem->delete($failedSnapshotId);
+        }
+
+        if (! $fileSystem->has($snapshotId)) {
+            $fileSystem->copy($filePath, $snapshotId);
+
+            $this->markTestIncomplete("File snapshot created for {$snapshotId}");
+        }
+
+        if (! $fileSystem->fileEquals($filePath, $snapshotId)) {
+            if ($this->shouldUpdateSnapshots()) {
+                $fileSystem->copy($filePath, $snapshotId);
+
+                $this->markTestIncomplete("File snapshot updated for {$snapshotId}");
+            }
+
+            $fileSystem->copy($filePath, $failedSnapshotId);
+
+            $this->fail("File did not match snapshot ({$snapshotId})");
+        }
+
+        $this->assertTrue(true);
+    }
+
     protected function createSnapshotAndMarkTestIncomplete(Snapshot $snapshot, $actual)
     {
         $snapshot->create($actual);

tests/Integration/AssertionTest.php

@@ -49,6 +49,14 @@ public function can_match_a_file_hash_snapshot()
         $this->assertMatchesFileHashSnapshot($filePath);
     }
 
+    /** @test */
+    public function can_match_a_file_snapshot()
+    {
+        $filePath = __DIR__.'/stubs/test_files/friendly_man.jpg';
+
+        $this->assertMatchesFileSnapshot($filePath);
+    }
+
     /** @test */
     public function can_do_multiple_snapshot_assertions()
     {

tests/Integration/MatchesSnapshotTest.php

@@ -68,6 +68,21 @@ public function it_can_create_a_snapshot_from_json()
         );
     }
 
+    /** @test */
+    public function it_can_create_a_snapshot_from_a_file()
+    {
+        $mockTrait = $this->getMatchesSnapshotMock();
+
+        $this->expectIncompleteMatchesSnapshotTest($mockTrait);
+
+        $mockTrait->assertMatchesFileSnapshot(__DIR__.'/stubs/test_files/friendly_man.jpg');
+
+        $this->assertSnapshotMatchesExample(
+            'files/MatchesSnapshotTest__it_can_create_a_snapshot_from_a_file__1.jpg',
+            'file.jpg'
+        );
+    }
+
     /** @test */
     public function it_can_match_an_existing_string_snapshot()
     {
@@ -140,6 +155,65 @@ public function it_can_mismatch_a_file_hash_snapshot()
         $mockTrait->assertMatchesFileHashSnapshot(__DIR__.'/stubs/example_snapshots/snapshot.json');
     }
 
+    /** @test */
+    public function it_can_mismatch_a_file_snapshot()
+    {
+        $mockTrait = $this->getMatchesSnapshotMock();
+
+        $this->expectFail($mockTrait);
+
+        $mockTrait->assertMatchesFileSnapshot(__DIR__.'/stubs/test_files/troubled_man.jpg');
+    }
+
+    /** @test */
+    public function it_needs_a_file_extension_to_do_a_file_snapshot_assertion()
+    {
+        $mockTrait = $this->getMatchesSnapshotMock();
+
+        $this->expectFail($mockTrait);
+
+        $filePath = __DIR__.'/stubs/test_files/file_without_extension';
+
+        $this->assertFileExists($filePath);
+
+        $mockTrait->assertMatchesFileSnapshot($filePath);
+    }
+
+    /** @test */
+    public function it_persists_the_failed_file_after_mismatching_a_file_snapshot()
+    {
+        $mockTrait = $this->getMatchesSnapshotMock();
+
+        $this->expectFail($mockTrait);
+
+        $mismatchedFile = __DIR__.'/stubs/test_files/troubled_man.jpg';
+
+        $mockTrait->assertMatchesFileSnapshot($mismatchedFile);
+
+        $persistedFailedFile = __DIR__.'/__snapshots__/files/MatchesSnapshotTest__it_persists_the_failed_file_after_mismatching_a_file_snapshot__1.jpg_failed.jpg';
+
+        $this->assertFileExists($persistedFailedFile);
+        $this->assertFileEquals($mismatchedFile, $persistedFailedFile);
+    }
+
+    /** @test */
+    public function it_deletes_the_persisted_failed_file_before_a_file_snapshot_assertion()
+    {
+        $mockTrait = $this->getMatchesSnapshotMock();
+
+        $mockTrait
+            ->expects($this->once())
+            ->method('assertTrue');
+
+        $persistedFailedFile = __DIR__.'/__snapshots__/files/MatchesSnapshotTest__it_deletes_the_persisted_failed_file_before_a_file_snapshot_assertion__1.jpg_failed.jpg';
+
+        $this->assertTrue(touch($persistedFailedFile));
+
+        $mockTrait->assertMatchesFileSnapshot(__DIR__.'/stubs/test_files/friendly_man.jpg');
+
+        $this->assertFileNotExists($persistedFailedFile);
+    }
+
     /** @test */
     public function it_can_update_a_string_snapshot()
     {
@@ -191,13 +265,37 @@ public function it_can_update_a_json_snapshot()
         );
     }
 
+    /** @test */
+    public function it_can_update_a_file_snapshot()
+    {
+        $_SERVER['argv'][] = '--update-snapshots';
+
+        $mockTrait = $this->getMatchesSnapshotMock();
+
+        $this->expectIncompleteMatchesSnapshotTest($mockTrait);
+
+        $mockTrait->assertMatchesFileSnapshot(__DIR__.'/stubs/test_files/friendly_man.jpg');
+
+        $this->assertSnapshotMatchesExample(
+            'files/MatchesSnapshotTest__it_can_update_a_file_snapshot__1.jpg',
+            'file.jpg'
+        );
+    }
+
     private function expectIncompleteMatchesSnapshotTest(PHPUnit_Framework_MockObject_MockObject $matchesSnapshotMock)
     {
         $matchesSnapshotMock
             ->expects($this->once())
             ->method('markTestIncomplete');
     }
 
+    private function expectFail(PHPUnit_Framework_MockObject_MockObject $matchesSnapshotMock)
+    {
+        $matchesSnapshotMock
+            ->expects($this->once())
+            ->method('fail');
+    }
+
     private function expectFailedMatchesSnapshotTest()
     {
         if (class_exists('PHPUnit\Framework\ExpectationFailedException')) {
@@ -216,6 +314,9 @@ private function getMatchesSnapshotMock(): PHPUnit_Framework_MockObject_MockObje
             'markTestIncomplete',
             'getSnapshotId',
             'getSnapshotDirectory',
+            'getFileSnapshotDirectory',
+            'fail',
+            'assertTrue',
         ];
 
         $matchesSnapshotMock = $this->getMockForTrait(
@@ -234,6 +335,11 @@ private function getMatchesSnapshotMock(): PHPUnit_Framework_MockObject_MockObje
             ->method('getSnapshotDirectory')
             ->willReturn(__DIR__.'/__snapshots__');
 
+        $matchesSnapshotMock
+            ->expects($this->any())
+            ->method('getFileSnapshotDirectory')
+            ->willReturn(__DIR__.'/__snapshots__/files');
+
         return $matchesSnapshotMock;
     }
 }