assertGolden Assertion

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.

Installation

You can install the package via composer:

composer require holgerk/assert-golden --dev

Usage

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

Trait Usage

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]
        );
    }
}

Function Usage

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.

Regenerate all expectations

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

Limitation

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 is more than one assertGolden call, it is not possible to detect a distinct position.

assertGoldenFile Assertion

assertGoldenFile may be useful if you have a large expected value and don't like it to be directly within your test.

Given the following code:

use PHPUnit\Framework\TestCase;
use function Holgerk\AssertGolden\assertGoldenFile;

class ExampleTest extends TestCase
{
    /** @test */
    public function some_feature(): void
    {
        assertGoldenFile(actual: ['color' => 'green']);    
    }
}

...during the first execution, the following file is generated:

<?php
// DO NOT EDIT (autogenerated by assertGoldenFile)

return [
    'color' => 'green',
];

The file is created in the same directory as the test.

For test file: /tests/ExampleTest.php and the test method: some_feature, the golden file: /tests/ExampleTest_some_feature.golden.php is generated.

When the file exists, it is used as expected value.

To regenerate the golden file, pass either: --update-golden as command line argument to the phpunit invocation or delete the golden file.

See Also

• 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

Credits

• nikic/php-parser

License

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