@blaze-cms/plugin-testing-base

Visual-regression helpers for Blaze frontends: full-page record and compare, with image masking, plus BrowserStack execution shared with @blaze-cms/plugin-testing-e2e.

Full-page record and compare

import { test, fullPageRecord, fullPageCompare } from '@blaze-cms/plugin-testing-base';

test('(record) home', async ({ page }, testInfo) => {
  await fullPageRecord({ page, testInfo, testIndex: 0, url: '/' });
});

Both settle the page first: navigate, remove .banner elements, scroll down in viewport steps to trigger lazy-loading, wait briefly for images, scroll back up and wait for network idle. Every wait has a ceiling enforced from the test runner, not by a timer inside the page, so a page that never stops lazy-loading can't stall the test. Pass budget to change the ceilings; the defaults are in DEFAULT_SETTLE:

await fullPageCompare({ page, testInfo, testIndex, url, budget: { totalMs: 90_000 } });

Pass mask to hide more elements than the built-in image masks, such as a widget whose content rotates on every load:

await fullPageCompare({ page, testInfo, testIndex, url, mask: ['.card--numbered-list'] });

The settle refuses to capture an error page: a response of 400 or above, other than 404, fails the test instead of becoming a baseline. That catches WAF blocks (403) and missing basic auth (401).

Upgrading from 0.2 or earlier changes how pages settle, so re-record baselines after upgrading.

BrowserStack

BrowserStack is on by default: runs go there whenever BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY are set. BLAZE_TEST_BROWSERSTACK=false forces local browsers, and =true makes missing credentials an error. In the Playwright config:

import { browserStackVR } from '@blaze-cms/plugin-testing-base';

const browserStack = browserStackVR({ site: 'mysite', storageState: cookiesStoreFile });

export default defineConfig({
  projects: browserStack.enabled ? browserStack.projects : localProjects(),
  workers: browserStack.workers ?? 2,
  // ...
});

Import test from this package rather than @playwright/test. It carries the fixtures that open real Android and iOS devices and mark BrowserStack sessions passed or failed.

BLAZE_TEST_PLAYWRIGHT_PLATFORM_COVERAGE takes the visual-regression names or the e2e package's names:

| Coverage | BrowserStack platforms | |---|---| | chrome-only / chromium (default) | Chrome / Windows 11 | | core | Chrome / Windows 11, Safari 26 / macOS, real Galaxy S25 | | desktop-only / desktop | Chrome, Edge, Firefox / Windows 11; Chrome / macOS; Safari 18 and 26 / macOS | | mobile-only / mobile | Real Android phones and tablets | | cross-breakpoint | Chrome / Windows 11 plus the real Galaxy Tab | | all | Everything |

BLAZE_TEST_BROWSERSTACK_PLATFORMS picks platform keys directly. The platform list and the other BLAZE_TEST_BROWSERSTACK_* settings are documented in the @blaze-cms/plugin-testing-e2e README.

Things to know:

• Baselines don't cross modes. Screenshots depend on the OS, fonts and device, so record and compare in the same mode and on the same platforms.
• Desktop platforms use a 1280x720 viewport to match local Desktop Chrome. Pass desktopViewport to change it.
• Real devices keep their hardware viewport. snapshotWithMask doesn't resize them, and specs that call page.setViewportSize() skip on them.
• Real iOS devices are left out of coverage-based selection for now. On 2026-10-01 the context opened but creating the page timed out on BrowserStack's side under a visual-regression config, while e2e suites ran on the same devices. Name them in BLAZE_TEST_BROWSERSTACK_PLATFORMS to try them. They also run without request routes or extraHTTPHeaders, which BrowserStack can't support there.
• mobile-only and core therefore mean Android and desktop until iOS is resolved: core is Chrome, Safari 26 on macOS and a real Galaxy S25.