holgerk/assert-golden

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

v2.0.7 2024-04-22 14:40 UTC

Requires

• php: ^8.1
• composer-runtime-api: *
• nikic/php-parser: ^4.16||^5
• phpunit/phpunit: ^8||^9||^10||^11
• symfony/var-exporter: ^4||^5||^6||^7

Requires (Dev)

• symfony/var-dumper: ^6||^7

MIT

• Holger Kohnen

• testing
• phpunit
• xunit

README

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

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.