[2.x] Add macros and interceptors to snapshot testing

[gehrisandro]

What:

• Bug Fix
• New Feature

Description:

The primary purpose of this PR is to ensure snapshot testing works with CSRF tokens and other random data.

As discussed here the goal is handle common types of random data (CSRF token, Livewire wire:id, etc.) within Pest respectively within the Plugin it belongs to.
Besides that the new API is public allowing users to add their own macros and interceptors.

There are two related plugin PRs:

• Laravel Plugin: [2.x] Add CSRF token handling for toMatchSnapshot pest-plugin-laravel#48
• Livewire Plugin: [2.x] Add ability to perform toMatchSnapshot on Livewire components pest-plugin-livewire#18

Intercept

This allows to intercept the toMatchSnapshot method for custom classes. This wouldn't be necessary to achieve the main goal but it makes the handling easier in the Plugins.

Example from the Laravel plugin PestServiceProvider. See this PR.

Snapshot::intercept(TestResponse::class, function (TestResponse $response): string {
    return $response->getContent();
});

Example for a custom interceptor:

test('create custom interceptor', function () {
    Snapshot::intercept(Color::class, function (Color $color): string {
        return $color->getStyle();
    });

    expect(new Color(255, 0, 0))
        ->toMatchSnapshot();
});

Nice side effect here, we can get rid of this unrelated TestResponse within the Pest core:

$this->value instanceof \Illuminate\Testing\TestResponse => $this->value->getContent(), // @phpstan-ignore-line

Macros

This allows to add macros to modify the snapshot string before the match is performed.

From the Livewire plugin PestServiceProvider. See this PR.

Snapshot::macro('livewire.wire-key', function (string $value) {
    return preg_replace('/wire:id="[0-9a-zA-Z]*"/', 'wire:id="..."', $value);
});

An example for a custom macro:

Snapshot::macro('time', function (string $value): string {
    return preg_replace('/[0-9]{2}:[0-9]{2}:[0-9]{2}/', '...', $value);
});

$value = 'The current time is '.now()->toTimeString();

expect($value)
    ->toMatchSnapshot();

Users can disable a Macro if they don't want to use it:

Snapshot::disableMacro('laravel.csrf');

Test repository

For an easy overview of all the new possibilities I've setup a test repository.

Documentation

For sure we have to update the documentation.
I am able to help there if you are happy with the decisions I made.

Draft

This and all related Plugin PRs are drafts. I have to clean them up and add more tests when you agree to the API suggested here.

Related:

#946

[owenvoke]

Personally, I love this and think it's really neat. 👍🏻 Will see what the others think though. 👀

[nunomaduro]

Fixed here: pestphp/docs@a0b413c.