WP VRT

Virtual pages for block/theme visual regression testing in WordPress.

Usage

• Block example: /wp-vrt/block/core-paragraph
• Block variation: /wp-vrt/block/core-button/outline
• Pattern: /wp-vrt/pattern/{pattern-slug}
• Template: /wp-vrt/template/{template-slug}
• Template part: /wp-vrt/template-part/{part-slug}
• Scenario: /wp-vrt/scenario/{scenario-slug}

Discovery Endpoint

/wp-json/wp-vrt/v1/discover

Returns a manifest of blocks, patterns, templates, template parts, and scenarios with URLs.

Pest Visual Regression

Install dev dependencies:

composer install

Install Playwright for screenshots:

npm install -D playwright

Admin UI Build

Install dependencies and build the admin UI bundle:

npm install
npm run build

For development:

npm run start

Run tests:

WP_VRT_BASE_URL="http://bedrock.test" composer test

You can override the Node binary:

NODE_BINARY="/usr/local/bin/node" composer test

To store screenshot PNGs in wp-content/wp-vrt-snapshots, set:

WP_VRT_SNAPSHOT_DIR="/path/to/wp-content/wp-vrt-snapshots" composer test

Scenarios (theme/plugin)

Register custom scenarios from your theme or another plugin.

add_filter('wp_vrt_register_scenarios', function ($scenarios) {
    $scenarios['button-states'] = [
        'title' => 'Button - All States',
        'description' => 'Default and outline buttons',
        'content' => '
            <!-- wp:buttons -->
            <div class="wp-block-buttons">
                <!-- wp:button -->
                <div class="wp-block-button"><a class="wp-block-button__link">Default</a></div>
                <!-- /wp:button -->

                <!-- wp:button {"className":"is-style-outline"} -->
                <div class="wp-block-button is-style-outline"><a class="wp-block-button__link">Outline</a></div>
                <!-- /wp:button -->
            </div>
            <!-- /wp:buttons -->
        ',
    ];

    return $scenarios;
});

You can also use a callable for content if you need custom logic.

Default Scenario Coverage

WP VRT does not ship any built-in scenarios. Scenarios are expected to be registered by your theme or other plugins.

Scenario	Coverage	Notes
(none)	N/A	Register scenarios via wp_vrt_register_scenarios

Block Discovery Filters

By default, WP VRT includes all registered blocks. You can narrow it down:

// Only include these blocks
add_filter('wp_vrt_block_allowlist', function () {
    return ['core/paragraph', 'core/heading', 'acf/hero'];
});

// Or exclude specific blocks
add_filter('wp_vrt_block_denylist', function () {
    return ['core/legacy-widget', 'plugin/experimental-block'];
});

Excluded Blocks

By default, WP VRT excludes the following blocks from discovery:

Block	Reason
core/social-link-* (39 variants)	Consolidated into single core/social-links block with all 39 social platforms as children
core/template-part	Cannot be meaningfully previewed without template context
core/pattern	Cannot be meaningfully previewed without theme context
core/widget-group	Requires legacy widget context

This results in 87 discoverable blocks instead of 129, with all blocks having meaningful sample content.

Enable/Disable Exposed Items

You can disable items from being exposed by default. Disabled items are hidden unless you enable the flag.

add_filter('wp_vrt_is_item_enabled', function ($enabled, $type, $id, $item) {
    if ($type === 'block' && $id === 'core/paragraph') {
        return false;
    }
    return $enabled;
}, 10, 4);

add_filter('wp_vrt_template_part_enabled', function ($enabled, $template) {
    return $template->slug !== 'header';
}, 10, 2);

Show disabled items:

• Admin UI: toggle on Tools → WP VRT
• Discovery: /wp-json/wp-vrt/v1/discover?include_disabled=1

To toggle items from the UI, use the disable/enable icon on each row.

Block Families

The admin UI groups blocks that are commonly used together. You can add or override families:

add_filter('wp_vrt_block_families', function ($families) {
    $families[] = [
        'title' => 'Accordion',
        'description' => 'Accordion with item blocks.',
        'blocks' => ['my/accordion', 'my/accordion-item'],
    ];
    return $families;
});

Block Sample Content

Dynamic blocks render from attributes only. Static blocks still require inner markup for rendering on the frontend, so WP VRT provides minimal HTML for core blocks. You can override per block:

add_filter('wp_vrt_block_content', function ($content, $block_name) {
    if ($block_name === 'core/paragraph') {
        return [[
            'attrs' => ['content' => 'Custom paragraph text'],
            'content' => '<p>Custom paragraph text</p>',
        ]];
    }
    return $content;
}, 10, 2);

WP-CLI Snapshots

Generate PNG snapshots into wp-content/wp-vrt-snapshots:

wp vrt snapshots --types=blocks --width=1200 --height=800

Options:

• --types=blocks,patterns,templates,parts,scenarios
• --base-url=https://example.test
• --dir=/path/to/wp-content/wp-vrt-snapshots
• --width=1200
• --height=800
• --node=/path/to/node

WP-CLI Test

Generate snapshots and run Pest in one command:

wp vrt test --base-url="http://bedrock.test"

Dynamic Content

Dynamic blocks that require post context (like query, post content, comments, etc.) are supported by providing a post context for rendering.

To provide a specific post ID for context:

add_filter('wp_vrt_dynamic_post_id', function () {
    return 123;
});

If no post ID is provided, WP VRT automatically:

1. Uses the first published post if one exists
2. Creates a temporary draft post and deletes it after rendering if no posts exist