Add update-snapshots wrapper binary (#245)

Add wrapper binaries to replace `-d --update-snapshots` syntax

Author: freekmurze

README.md

@@ -169,20 +169,48 @@ FAILURES!
 Tests: 1, Assertions: 1, Failures: 1.
 ```
 
-When we expect a changed value, we need to tell the test runner to update the existing snapshots instead of failing the test. This is possible by adding  a`-d --update-snapshots` flag to the `phpunit` command, or setting the `UPDATE_SNAPSHOTS` env var to `true`.
+When we expect a changed value, we need to tell the test runner to update the existing snapshots instead of failing the test. The package ships a wrapper binary that runs PHPUnit with the right environment variable set:
 
 ```
-> ./vendor/bin/phpunit -d --update-snapshots
+> ./vendor/bin/update-snapshots
 
 OK (1 test, 1 assertion)
 ```
 
+`vendor/bin/update-snapshots` accepts the same arguments as `phpunit`, so you can target a specific test:
+
+```
+> ./vendor/bin/update-snapshots tests/OrderTest.php
+```
+
 As a result, our snapshot file returns "bar" instead of "foo".
 
 ```txt
 bar
 ```
 
+You can also set the `UPDATE_SNAPSHOTS` environment variable directly. This is useful in CI, or when you want to define a Composer script for your project.
+
+```
+> UPDATE_SNAPSHOTS=true ./vendor/bin/phpunit
+```
+
+A common pattern is to add an `update-snapshots` script to your project's `composer.json`:
+
+```json
+{
+    "scripts": {
+        "update-snapshots": "UPDATE_SNAPSHOTS=true vendor/bin/phpunit"
+    }
+}
+```
+
+You can then run `composer update-snapshots` (and pass extra arguments via `composer update-snapshots -- tests/OrderTest.php`).
+
+#### Why not `phpunit -d --update-snapshots`?
+
+Earlier versions of this package documented `phpunit -d --update-snapshots` as the way to enable updates. That syntax abuses PHPUnit's `-d` flag, which is designed to set `php.ini` values. Since [PHPUnit 12.5.12](https://github.com/sebastianbergmann/phpunit/commit/87f68b992979f9e4ad485be959b5e9d0c21597f2), failed `ini_set()` calls produce a visible `Failed to set "--update-snapshots=1"` warning, surfacing the misuse. The wrapper binary and the environment variable replace that approach. The legacy CLI argument still works for backwards compatibility, but produces the warning on PHPUnit 12.5.12 and later.
+
 ### 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:
@@ -311,29 +339,39 @@ $this->assertMatchesSnapshot($something->toYaml(), new MyYamlDriver());
 
 ### Usage in CI
 
-When running your tests in Continuous Integration you would possibly want to disable the creation of snapshots.
+When running your tests in Continuous Integration you would possibly want to disable the creation of snapshots, so missing snapshots cause the build to fail instead of being silently created.
 
-By using the `--without-creating-snapshots` parameter or by setting the `CREATE_SNAPSHOTS` env var to `false`, PHPUnit will fail if the snapshots don't exist.
+Set the `CREATE_SNAPSHOTS=false` environment variable when invoking PHPUnit:
 
 ```bash
-> ./vendor/bin/phpunit -d --without-creating-snapshots
+> CREATE_SNAPSHOTS=false ./vendor/bin/phpunit
 
 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 the `CREATE_SNAPSHOTS=false` env var, or `-d --no-create-snapshots` of PHPUnit's CLI arguments.
+You can enable snapshot creation by running `vendor/bin/phpunit` directly, or by unsetting the `CREATE_SNAPSHOTS=false` environment variable.
 ```
 
+```json
+{
+    "scripts": {
+        "test:ci": "CREATE_SNAPSHOTS=false vendor/bin/phpunit"
+    }
+}
+```
+
+> Earlier versions of this package documented `phpunit -d --without-creating-snapshots`. Since [PHPUnit 12.5.12](https://github.com/sebastianbergmann/phpunit/commit/87f68b992979f9e4ad485be959b5e9d0c21597f2), that syntax produces a `Failed to set "--without-creating-snapshots=1"` test runner warning because it abuses PHPUnit's `-d` flag (which is designed for `php.ini` values). The `CREATE_SNAPSHOTS=false` environment variable replaces that approach.
+
 ### Usage with parallel testing
 
-If you want to run your test in parallel with a tool like [Paratest](https://github.com/paratestphp/paratest), ou with the `php artisan test --parallel` command of Laravel, you will have to use the environment variables.
+If you want to run your test in parallel with a tool like [Paratest](https://github.com/paratestphp/paratest), or with the `php artisan test --parallel` command of Laravel, you will have to use the environment variables.
 
 
 ```bash
 > CREATE_SNAPSHOTS=false php artisan test --parallel
 
 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 the `CREATE_SNAPSHOTS=false` env var, or `-d --no-create-snapshots` of PHPUnit's CLI arguments.
+You can enable snapshot creation by running `vendor/bin/phpunit` directly, or by unsetting the `CREATE_SNAPSHOTS=false` environment variable.
 ```
 
 ### A note for Windows users

bin/_run-phpunit.php

@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * Locates the PHPUnit binary and runs it. Shared helper used by the
+ * `update-snapshots` and `without-creating-snapshots` wrappers, which set
+ * the relevant environment variable before requiring this file.
+ */
+
+$candidates = [];
+
+if (isset($GLOBALS['_composer_autoload_path'])) {
+    $candidates[] = dirname($GLOBALS['_composer_autoload_path']).'/phpunit/phpunit/phpunit';
+}
+
+$candidates[] = dirname(__DIR__, 3).'/phpunit/phpunit/phpunit';
+$candidates[] = dirname(__DIR__).'/vendor/phpunit/phpunit/phpunit';
+
+foreach ($candidates as $phpunit) {
+    if (file_exists($phpunit)) {
+        require $phpunit;
+
+        return;
+    }
+}
+
+fwrite(STDERR, 'Could not locate PHPUnit. Make sure phpunit/phpunit is installed.'.PHP_EOL);
+exit(1);

bin/update-snapshots

@@ -0,0 +1,42 @@
+#!/usr/bin/env php
+<?php
+
+/*
+ * This wrapper sets the UPDATE_SNAPSHOTS environment variable and then runs
+ * PHPUnit, so snapshots are updated for this run only.
+ *
+ * It exists because the previously documented syntax (`phpunit -d --update-snapshots`)
+ * abuses PHPUnit's `-d` flag, which is meant to set php.ini values. Since PHPUnit
+ * 12.5.12 (https://github.com/sebastianbergmann/phpunit/commit/87f68b9), failed
+ * ini_set() calls produce a visible test runner warning, surfacing that misuse.
+ */
+
+// Capture whatever the env var was before this script ran, so we can restore it
+// on shutdown. Without this, code running after PHPUnit (shutdown handlers, parent
+// processes that include this file) would observe a state mutation they didn't ask
+// for. Env values are always strings, so `null` unambiguously means "wasn't set".
+$originalGetenv = getenv('UPDATE_SNAPSHOTS');
+$originalEnv = $_ENV['UPDATE_SNAPSHOTS'] ?? null;
+$originalServer = $_SERVER['UPDATE_SNAPSHOTS'] ?? null;
+
+register_shutdown_function(static function () use ($originalGetenv, $originalEnv, $originalServer): void {
+    putenv($originalGetenv === false ? 'UPDATE_SNAPSHOTS' : 'UPDATE_SNAPSHOTS='.$originalGetenv);
+
+    unset($_ENV['UPDATE_SNAPSHOTS'], $_SERVER['UPDATE_SNAPSHOTS']);
+
+    if ($originalEnv !== null) {
+        $_ENV['UPDATE_SNAPSHOTS'] = $originalEnv;
+    }
+
+    if ($originalServer !== null) {
+        $_SERVER['UPDATE_SNAPSHOTS'] = $originalServer;
+    }
+});
+
+// Set in all three locations so getenv(), $_ENV[] and $_SERVER[] reads all see the
+// value, regardless of the user's `variables_order` ini setting.
+putenv('UPDATE_SNAPSHOTS=true');
+$_ENV['UPDATE_SNAPSHOTS'] = 'true';
+$_SERVER['UPDATE_SNAPSHOTS'] = 'true';
+
+require __DIR__.'/_run-phpunit.php';

composer.json

@@ -47,6 +47,9 @@
             "Spatie\\Snapshots\\Test\\": "tests"
         }
     },
+    "bin": [
+        "bin/update-snapshots"
+    ],
     "scripts": {
         "test": "phpunit"
     },

src/MatchesSnapshots.php

@@ -137,29 +137,32 @@ protected function getFileSnapshotDirectory(): string
      * Determines whether or not the snapshot should be updated instead of
      * matched.
      *
-     * Override this method it you want to use a different flag or mechanism
-     * than `-d --update-snapshots` or `UPDATE_SNAPSHOTS=true` env var.
+     * Override this method if you want to use a different flag or mechanism
+     * than `vendor/bin/update-snapshots` or the `UPDATE_SNAPSHOTS=true` env var.
      */
     protected function shouldUpdateSnapshots(): bool
     {
-        if (in_array('--update-snapshots', $_SERVER['argv'], true)) {
+        if (getenv('UPDATE_SNAPSHOTS') === 'true') {
             return true;
         }
 
-        return getenv('UPDATE_SNAPSHOTS') === 'true';
+        return in_array('--update-snapshots', $_SERVER['argv'], true);
     }
 
     /*
      * Determines whether or not the snapshot should be created instead of
      * matched.
      *
      * Override this method if you want to use a different flag or mechanism
-     * than `-d --without-creating-snapshots` or `CREATE_SNAPSHOTS=false` env var.
+     * than the `CREATE_SNAPSHOTS=false` env var.
      */
     protected function shouldCreateSnapshots(): bool
     {
-        return ! in_array('--without-creating-snapshots', $_SERVER['argv'], true)
-            && getenv('CREATE_SNAPSHOTS') !== 'false';
+        if (getenv('CREATE_SNAPSHOTS') === 'false') {
+            return false;
+        }
+
+        return ! in_array('--without-creating-snapshots', $_SERVER['argv'], true);
     }
 
     protected function resolveSnapshotId(?string $id = null): string
@@ -296,8 +299,8 @@ protected function updateSnapshotAndMarkTestIncomplete(Snapshot $snapshot, $actu
     protected function rethrowExpectationFailedExceptionWithUpdateSnapshotsPrompt($exception): void
     {
         $newMessage = $exception->getMessage()."\n\n".
-            'Snapshots can be updated by passing '.
-            '`-d --update-snapshots` through PHPUnit\'s CLI arguments.';
+            'Snapshots can be updated by running `vendor/bin/update-snapshots`, '.
+            'or by setting the `UPDATE_SNAPSHOTS=true` environment variable.';
 
         $exceptionReflection = new ReflectionObject($exception);
 
@@ -320,9 +323,8 @@ 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 '.
-            '`-d --without-creating-snapshots` of PHPUnit\'s CLI arguments.'
+            'You can enable snapshot creation by running `vendor/bin/phpunit` directly, '.
+            'or by unsetting the `CREATE_SNAPSHOTS=false` environment variable.'
         );
     }
 }

tests/Integration/MatchesSnapshotTest.php

@@ -2,7 +2,6 @@
 
 namespace Spatie\Snapshots\Test\Integration;
 
-use PHPUnit\Framework\AssertionFailedError;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\ExpectationFailedException;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -478,13 +477,17 @@ private function expectIncompleteMatchesSnapshotTest(MockObject $matchesSnapshot
 
     private function expectFail(MockObject $matchesSnapshotMock, string $message)
     {
-        $this->expectException(AssertionFailedError::class);
+        // We throw a plain RuntimeException from the mock instead of
+        // AssertionFailedError because PHPUnit 12.5+ tracks AssertionFailedError
+        // thrown from a mock as a test failure even when user code catches it.
+        $this->expectException(\RuntimeException::class);
+        $this->expectExceptionMessage($message);
 
         $matchesSnapshotMock
             ->expects($this->once())
             ->method('fail')
             ->with($message)
-            ->willThrowException(new AssertionFailedError);
+            ->willThrowException(new \RuntimeException($message));
     }
 
     private function expectFailedMatchesSnapshotTest()
@@ -563,7 +566,7 @@ public function it_doesnt_create_a_regular_snapshot_and_mismatches_if_asked()
         $this->expectFail(
             $mockTrait,
             "Snapshot \"MatchesSnapshotTest__it_doesnt_create_a_regular_snapshot_and_mismatches_if_asked__1.txt\" 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."
+            'You can enable snapshot creation by running `vendor/bin/phpunit` directly, or by unsetting the `CREATE_SNAPSHOTS=false` environment variable.'
         );
 
         $mockTrait->assertMatchesSnapshot('Bar');
@@ -580,7 +583,7 @@ public function it_doesnt_create_a_file_snapshot_and_mismatches_if_asked()
         $this->expectFail(
             $mockTrait,
             "Snapshot \"MatchesSnapshotTest__it_doesnt_create_a_file_snapshot_and_mismatches_if_asked__1.jpg_failed.jpg\" 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."
+            'You can enable snapshot creation by running `vendor/bin/phpunit` directly, or by unsetting the `CREATE_SNAPSHOTS=false` environment variable.'
         );
 
         $mockTrait->assertMatchesFileSnapshot(__DIR__.'/stubs/test_files/friendly_man.jpg');
@@ -597,7 +600,7 @@ public function it_doesnt_create_a_regular_snapshot_and_mismatches_if_asked_with
         $this->expectFail(
             $mockTrait,
             "Snapshot \"MatchesSnapshotTest__it_doesnt_create_a_regular_snapshot_and_mismatches_if_asked_with_env_var__1.txt\" 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."
+            'You can enable snapshot creation by running `vendor/bin/phpunit` directly, or by unsetting the `CREATE_SNAPSHOTS=false` environment variable.'
         );
 
         $mockTrait->assertMatchesSnapshot('Bar');
@@ -614,7 +617,7 @@ public function it_doesnt_create_a_file_snapshot_and_mismatches_if_asked_with_en
         $this->expectFail(
             $mockTrait,
             "Snapshot \"MatchesSnapshotTest__it_doesnt_create_a_file_snapshot_and_mismatches_if_asked_with_env_var__1.jpg_failed.jpg\" 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."
+            'You can enable snapshot creation by running `vendor/bin/phpunit` directly, or by unsetting the `CREATE_SNAPSHOTS=false` environment variable.'
         );
 
         $mockTrait->assertMatchesFileSnapshot(__DIR__.'/stubs/test_files/friendly_man.jpg');