Same as assertEquals, but when null is given as argument, the test file is automatically edited and null is substituted with the actual value

Given the following code:

assertGolden(
    null,                 // <- expectation value
    ['color' => 'golden'] // <- actual value
);

...during the first execution null replaced with the actual value:

assertGolden(
    [
        'color' => 'golden',
    ],
    ['color' => 'golden']
);

In principle, it's about saving oneself the recurring work of writing, updating and copying an expectation.

You can install the package via composer:

composer require holgerk/assert-golden --dev

Just pass null to the assertGolden expectation and null will be automatically replaced during the first test run.

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\Test;

use Holgerk\AssertGolden\AssertGolden;

class ExampleTest extends TestCase
{
    use AssertGolden;

    #[Test]
    public function test(): void
    {
        // via method call...
        $this->assertGolden(
            null,
            ['a' => 1, 'b' => 2]
        );
        
        // ...or static call
        self::assertGolden(
            null,
            ['a' => 1, 'b' => 2]
        );
    }
}

use PHPUnit\Framework\TestCase;
use PHPUnit\Framework\Attributes\Test;

use function Holgerk\AssertGolden\assertGolden;

class ExampleTest extends TestCase
{
    #[Test]
    public function test(): void
    {
        assertGolden(
            null,
            ['a' => 1, 'b' => 2]
        );
    }
}

Later you can edit the expectation by hand or insert null again to have it automatically replaced.

If you want to regenerate all expectations at once you can add the argument: --update-golden to your phpunit invocation.

# regenerate all expectations at once from their actual values
./vendor/bin/phpunit --update-golden

It is not possible to have more than one assertGolden call on one line. Because the automatic replacement is based on the debug_backtrace function, which gives us the line number and file of the assertGolden caller, and the composer package nikic/php-parser, which is used to get the exact start and end position of the expectation argument. So if there are more than one assertGolden call it is not possible to detect a distinct position.

• phpunit-snapshot-assertions
  This plugin also facilitates the automatic generation of expectations from the actual value, but it will store the generated expectation in separate files.
• pest-plugin-equal-golden
  Same thing for pestphp

• nikic/php-parser

The MIT License (MIT). Please see License File for more information.