nuxt-spec 0.2.3 → 0.2.4-alpha.2

package/utils/index.d.ts

@@ -1,70 +1,70 @@
-import type { NuxtPage } from '@nuxt/test-utils'
-
-/**
- * Visit a specified URL and return the page instance for further interaction.
- *
- * @param pageName - Path segment appended to the base URL (e.g. `'about'` → `/<about>`)
- * @returns Playwright page instance after navigation and hydration
- */
-export declare function gotoPage(pageName: string): Promise<NuxtPage>
-
-/**
- * Extract inner HTML content from a specified element on a given page.
- *
- * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
- * @param element - CSS selector identifying the target element
- * @returns The inner HTML of the matched element
- */
-export declare function getDataHtml(page: NuxtPage | string, element: string): Promise<string>
-
-/**
- * Execute an API call by clicking a trigger element, wait for a successful
- * response matching the target URL, then extract the inner HTML from the
- * response element.
- *
- * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
- * @param triggerElement - CSS selector for the clickable element that triggers the API request
- * @param targetUrl - Substring matched against the response URL to identify the expected API call
- * @param responseElement - CSS selector for the element displaying the API response
- * @returns The inner HTML of the response element
- */
-export declare function getAPIResultHtml(
-  page: NuxtPage | string,
-  triggerElement: string,
-  targetUrl: string,
-  responseElement: string,
-): Promise<string>
-
-export interface CompareScreenshotOptions {
-  /** Name of the PNG file used for baseline storage and comparison (defaults to route and `index.png` for `/`) */
-  fileName?: string
-  /** Directory for baseline/current screenshots, relative to project root (defaults to `test/e2e`) */
-  targetDir?: string
-  /** CSS selector for a specific element to capture (defaults to full page) */
-  selector?: string
-  /** Max ratio of different pixels (0–1). Default: 0 (exact match) */
-  maxDiffPixelRatio?: number
-  /** Max absolute number of different pixels. Takes precedence over `maxDiffPixelRatio` when set. Default: 0 (exact match) */
-  maxDiffPixels?: number
-  /** Per-pixel color distance threshold (0–1). Lower = stricter. Default: 0.1 */
-  threshold?: number
-}
-
-/**
- * Capture a browser screenshot and compare it against a stored baseline PNG.
- * When run with `-u` / `--update`, or when no baseline exists yet, the current
- * screenshot is saved as the new baseline.
- *
- * Comparison uses pixelmatch for perceptual pixel diffing. By default,
- * zero differing pixels are allowed (exact match). Set `maxDiffPixelRatio`
- * or `maxDiffPixels` to tolerate cross-platform rendering differences.
- *
- * @param page - Playwright page instance obtained from `createPage()`
- * @param options - extra options (see `CompareScreenshotOptions`)
- * @returns `true` when the screenshot matches the baseline (or a new baseline was saved)
- * @throws Fails the current Vitest test when a mismatch is detected
- */
-export declare function compareScreenshot(
-  page: NuxtPage,
-  options?: CompareScreenshotOptions,
-): Promise<boolean>
+import type { NuxtPage } from '@nuxt/test-utils'
+
+/**
+ * Visit a specified URL and return the page instance for further interaction.
+ *
+ * @param pageName - Path segment appended to the base URL (e.g. `'about'` → `/<about>`)
+ * @returns Playwright page instance after navigation and hydration
+ */
+export declare function gotoPage(pageName: string): Promise<NuxtPage>
+
+/**
+ * Extract inner HTML content from a specified element on a given page.
+ *
+ * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
+ * @param element - CSS selector identifying the target element
+ * @returns The inner HTML of the matched element
+ */
+export declare function getDataHtml(page: NuxtPage | string, element: string): Promise<string>
+
+/**
+ * Execute an API call by clicking a trigger element, wait for a successful
+ * response matching the target URL, then extract the inner HTML from the
+ * response element.
+ *
+ * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
+ * @param triggerElement - CSS selector for the clickable element that triggers the API request
+ * @param targetUrl - Substring matched against the response URL to identify the expected API call
+ * @param responseElement - CSS selector for the element displaying the API response
+ * @returns The inner HTML of the response element
+ */
+export declare function getAPIResultHtml(
+  page: NuxtPage | string,
+  triggerElement: string,
+  targetUrl: string,
+  responseElement: string,
+): Promise<string>
+
+export interface CompareScreenshotOptions {
+  /** Name of the PNG file used for baseline storage and comparison (defaults to route and `index.png` for `/`) */
+  fileName?: string
+  /** Directory for baseline/current screenshots, relative to project root (defaults to `test/e2e`) */
+  targetDir?: string
+  /** CSS selector for a specific element to capture (defaults to full page) */
+  selector?: string
+  /** Max ratio of different pixels (0–1). Default: 0 (exact match) */
+  maxDiffPixelRatio?: number
+  /** Max absolute number of different pixels. Takes precedence over `maxDiffPixelRatio` when set. Default: 0 (exact match) */
+  maxDiffPixels?: number
+  /** Per-pixel color distance threshold (0–1). Lower = stricter. Default: 0.1 */
+  threshold?: number
+}
+
+/**
+ * Capture a browser screenshot and compare it against a stored baseline PNG.
+ * When run with `-u` / `--update`, or when no baseline exists yet, the current
+ * screenshot is saved as the new baseline.
+ *
+ * Comparison uses pixelmatch for perceptual pixel diffing. By default,
+ * zero differing pixels are allowed (exact match). Set `maxDiffPixelRatio`
+ * or `maxDiffPixels` to tolerate cross-platform rendering differences.
+ *
+ * @param page - Playwright page instance obtained from `createPage()`
+ * @param options - extra options (see `CompareScreenshotOptions`)
+ * @returns `true` when the screenshot matches the baseline (or a new baseline was saved)
+ * @throws Fails the current Vitest test when a mismatch is detected
+ */
+export declare function compareScreenshot(
+  page: NuxtPage,
+  options?: CompareScreenshotOptions,
+): Promise<boolean>

package/utils/index.ts

@@ -1,12 +1,12 @@
-import { gotoPage, getDataHtml, getAPIResultHtml } from './e2e'
-import { compareScreenshot } from './screenshot'
-import type { CompareScreenshotOptions } from './screenshot'
-
-export {
-  compareScreenshot,
-  gotoPage,
-  getDataHtml,
-  getAPIResultHtml,
-}
-
-export type { CompareScreenshotOptions }
+import { gotoPage, getDataHtml, getAPIResultHtml } from './e2e'
+import { compareScreenshot } from './screenshot'
+import type { CompareScreenshotOptions } from './screenshot'
+
+export {
+  compareScreenshot,
+  gotoPage,
+  getDataHtml,
+  getAPIResultHtml,
+}
+
+export type { CompareScreenshotOptions }

package/utils/screenshot/report-entry.html

@@ -0,0 +1,8 @@
+<div class="failure">
+  <h2>{{FILE_NAME}}</h2>
+  <p class="message">{{MESSAGE}}</p>
+  <div class="pair">
+    <figure><figcaption>Baseline image</figcaption><img src="{{BASELINE_URI}}" alt="Baseline image for reference"></figure>
+    <figure><figcaption>Actual screenshot</figcaption><img src="{{ACTUAL_URI}}" alt="Actual screenshot taken"></figure>
+  </div>
+</div>

package/utils/screenshot/report-head.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Visual Regression Report</title>
+<style>
+  body { font-family: system-ui, sans-serif; margin: 2rem; background: #f5f5f5; color: #222; }
+  h1 { font-size: 1.4rem; }
+  .failure { background: #fff; border: 1px solid #ddd; border-radius: 8px; padding: 1rem; margin: 1rem 0; box-shadow: 0 1px 3px rgba(0, 0, 0, .1); }
+  .failure h2 { font-size: 1rem; margin: 0 0 .5rem; }
+  .failure .message { color: #b00; font-size: .85rem; margin: 0 0 .75rem; }
+  .pair { display: flex; gap: 1rem; flex-wrap: wrap; }
+  .pair figure { margin: 0; flex: 1 1 0; min-width: 240px; }
+  .pair figcaption { font-size: .8rem; margin-bottom: .25rem; font-weight: bold; }
+  .pair figure:first-child figcaption { color: #0b0; }
+  .pair figure:last-child figcaption { color: #b00; }
+  .pair img { max-width: 100%; background: #fff; }
+  .pair figure:first-child img { border: 2px solid #0b0; }
+  .pair figure:last-child img { border: 2px solid #b00; }
+</style>
+</head>
+<body>
+<h1>Visual Regression Report - {{TIMESTAMP}}</h1>
+<!-- BEGIN failed screenshot entries -->

package/utils/screenshot/report-tail.html

@@ -0,0 +1,4 @@
+<!-- END failed screenshot entries -->
+ <div>Generated by <a href="https://github.com/nuxt/nuxt-spec">Nuxt Spec</a> @ {{TIMESTAMP}}</div>
+</body>
+</html>

package/utils/screenshot/report-utils.ts

@@ -0,0 +1,210 @@
+import { exec } from 'node:child_process'
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import { resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { DecodedPng } from 'fast-png'
+
+const templatesDir = resolve(fileURLToPath(import.meta.url), '..')
+const REPORT_ENTRY = readFileSync(resolve(templatesDir, 'report-entry.html'), 'utf-8')
+const REPORT_PATH = resolve(process.cwd(), '.report-path')
+const REPORT_LOCK = resolve(process.cwd(), '.report-lock')
+
+// create report file on first call
+// protected from parallel execution issues
+export function ensureReportCreated(targetDir = 'test/e2e'): void {
+  withConcurrentLock(() => {
+    let reportPath: string
+
+    if (existsSync(REPORT_PATH)) {
+      // Keep exactly one shared report per test run; first writer wins.
+      reportPath = readFileSync(REPORT_PATH, 'utf-8').trim()
+    } else {
+      const root = process.cwd()
+      const dir = resolveWithin(root, targetDir)
+      const fileTimestamp = process.env.SCREENSHOT_REPORT_TIMESTAMP ?? reportTimestamp(new Date())
+      reportPath = resolve(dir, '__current__', `report-${fileTimestamp}.html`)
+      writeFileSync(REPORT_PATH, reportPath)
+    }
+
+    process.env.SCREENSHOT_REPORT_PATH = reportPath
+    if (!reportPath || existsSync(reportPath)) return
+
+    const titleTimestamp = process.env.SCREENSHOT_REPORT_TITLE ?? reportTimestamp(new Date(), true)
+    mkdirSync(resolve(reportPath, '..'), { recursive: true })
+
+    const template = readFileSync(resolve(templatesDir, 'report-head.html'), 'utf-8')
+    const report = template.replace('{{TIMESTAMP}}', titleTimestamp)
+    writeFileSync(reportPath, report)
+  })
+}
+
+// append a side-by-side baseline/actual comparison
+// to the HTML report if the screenshots don't match
+// protected from parallel execution issues
+export function appendToReport(fileName: string, message: string, baseline: Uint8Array, actual: Uint8Array): void {
+  const baselineUri = `data:image/png;base64,${Buffer.from(baseline).toString('base64')}`
+  const actualUri = `data:image/png;base64,${Buffer.from(actual).toString('base64')}`
+
+  const entry = REPORT_ENTRY
+    .replace('{{FILE_NAME}}', escapeHtml(fileName))
+    .replace('{{MESSAGE}}', escapeHtml(message))
+    .replace('{{BASELINE_URI}}', baselineUri)
+    .replace('{{ACTUAL_URI}}', actualUri)
+
+  withConcurrentLock(() => {
+    const reportPath = process.env.SCREENSHOT_REPORT_PATH || (existsSync(REPORT_PATH)
+      ? readFileSync(REPORT_PATH, 'utf-8').trim()
+      : '')
+    if (!reportPath || !existsSync(reportPath)) return
+
+    appendFileSync(reportPath, entry)
+  })
+}
+
+// Vitest globalSetup entry point
+// - computes stable timestamp values and exposes them via env variables
+// - the report file itself is created lazily on first compareScreenshot call
+// - provides a callback to close the HTML report once tests are finished (if it was created)
+export function screenshotSetup() {
+  const NOW = new Date()
+  const fileTimestamp = reportTimestamp(NOW)
+  const titleTimestamp = reportTimestamp(NOW, true)
+
+  process.env.SCREENSHOT_REPORT_TIMESTAMP = fileTimestamp
+  process.env.SCREENSHOT_REPORT_TITLE = titleTimestamp
+
+  return () => {
+    if (!existsSync(REPORT_PATH)) return
+
+    const reportPath = readFileSync(REPORT_PATH, 'utf-8').trim()
+    unlinkSync(REPORT_PATH)
+
+    if (!reportPath) return
+    if (!existsSync(reportPath)) return
+
+    let footer = readFileSync(resolve(templatesDir, 'report-tail.html'), 'utf-8')
+    footer = footer.replace('{{TIMESTAMP}}', new Date().toISOString())
+    appendFileSync(reportPath, footer)
+    console.log(`\n(nuxt-spec) Visual regression report available at:\nfile://${reportPath}`)
+
+    if (!process.env.CI) {
+      console.log('(nuxt-spec) Opening report in default browser...')
+      const openCmd = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'start' : 'xdg-open'
+      exec(`${openCmd} "${reportPath}"`, (err) => {
+        if (err) {
+          console.log('(nuxt-spec) Failed to automatically open report')
+        }
+      })
+    }
+
+    console.log('\n')
+  }
+}
+
+// helper to keep user-provided targetDir inside the current project root
+export function resolveWithin(base: string, segment: string): string {
+  const target = resolve(base, segment)
+  if (target !== base && !target.startsWith(base + sep)) {
+    throw new Error(`Invalid path: "${segment}" resolves outside of "${base}"`)
+  }
+  return target
+}
+
+// helper for bridging difference between Vitest PNG saving and fast-png encoding
+export function toRGBA(img: DecodedPng): Uint8Array {
+  const { width, height, data, channels = 4 } = img
+  if (channels === 4) return data as Uint8Array
+  const pixels = width * height
+  const rgba = new Uint8Array(pixels * 4)
+  for (let i = 0; i < pixels; i++) {
+    rgba[i * 4] = data[i * 3]
+    rgba[i * 4 + 1] = data[i * 3 + 1]
+    rgba[i * 4 + 2] = data[i * 3 + 2]
+    rgba[i * 4 + 3] = 255
+  }
+  return rgba
+}
+
+// protection from parallel execution issues
+function withConcurrentLock<T>(fn: () => T): T {
+  const start = Date.now()
+
+  while (true) {
+    try {
+      // try acquiring the lock
+      writeFileSync(REPORT_LOCK, String(process.pid), { flag: 'wx' })
+      break
+    } catch (error) {
+      // we only expect "file already exists" error
+      // otherwise it is an issue
+      const code = (error as NodeJS.ErrnoException).code
+      if (code !== 'EEXIST') throw error
+
+      try {
+        const lockAge = Date.now() - statSync(REPORT_LOCK).mtimeMs
+        if (lockAge > 30_000) {
+          // stale lock
+          unlinkSync(REPORT_LOCK)
+          continue
+        }
+      } catch {
+        // lock disappeared between checks, retry acquisition
+      }
+
+      if (Date.now() - start > 10_000) {
+        // not successful in 10 minutes, give up
+        throw new Error('Timed out while waiting for screenshot report lock', {
+          cause: error,
+        })
+      }
+
+      // sleep before next attempt
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25)
+    }
+  }
+
+  try {
+    return fn()
+  } finally {
+    try {
+      unlinkSync(REPORT_LOCK)
+    } catch {
+      // lock file may already be removed
+    }
+  }
+}
+
+// timestamp string
+// separators=false produces YYYYMMDDHHMMSS for report file name
+// separators=true produces YYYY-MM-DD HH:MM:SS for report title
+function reportTimestamp(date: Date, separators = false): string {
+  const pad2 = (n: number) => String(n).padStart(2, '0')
+  const dateSeparator = separators ? '-' : ''
+  const midSeparator = separators ? ' ' : ''
+  const timeSeparator = separators ? ':' : ''
+  return [
+    date.getFullYear(),
+    dateSeparator,
+    pad2(date.getMonth() + 1),
+    dateSeparator,
+    pad2(date.getDate()),
+    midSeparator,
+    pad2(date.getHours()),
+    timeSeparator,
+    pad2(date.getMinutes()),
+    timeSeparator,
+    pad2(date.getSeconds()),
+  ].join('')
+}
+
+// helper to escape a string for safe interpolation into the HTML report
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, char => ({
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    '\'': '&#39;',
+  }[char] ?? char))
+}

package/utils/screenshot.ts

@@ -1,89 +1,104 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { expect } from 'vitest'
-import { decode, type DecodedPng } from 'fast-png'
-import pixelmatch from 'pixelmatch'
-import type { NuxtPage } from '@nuxt/test-utils'
-
-export interface CompareScreenshotOptions {
-  /** Name of the PNG file used for baseline storage and comparison (defaults to route and `index.png` for `/`) */
-  fileName?: string
-  /** Directory for baseline/current screenshots, relative to project root (defaults to `test/e2e`) */
-  targetDir?: string
-  /** CSS selector for a specific element to capture (defaults to full page) */
-  selector?: string
-  /** Max ratio of different pixels (0–1). Default: 0 (exact match) */
-  maxDiffPixelRatio?: number
-  /** Max absolute number of different pixels. Takes precedence over `maxDiffPixelRatio` when set. Default: 0 (exact match) */
-  maxDiffPixels?: number
-  /** Per-pixel color distance threshold (0–1). Lower = stricter. Default: 0.1 */
-  threshold?: number
-}
-
-// capture a browser screenshot and compare it against a stored baseline PNG
-export async function compareScreenshot(page: NuxtPage, options?: CompareScreenshotOptions): Promise<boolean> {
-  const dir = resolve(process.cwd(), options?.targetDir ?? 'test/e2e')
-  const baselineDir = resolve(dir, '__baseline__')
-  const currentDir = resolve(dir, '__current__')
-
-  const route = page.url().substring(page.url().lastIndexOf('/') + 1) || 'index'
-  const fileName = options?.fileName ?? `${route}.png`
-
-  // capture element specified by locator or a full-page screenshot as PNG
-  const screenshot = options?.selector
-    ? await page.locator(options.selector).screenshot()
-    : await page.screenshot({ fullPage: true })
-  const baselinePath = resolve(baselineDir, fileName)
-
-  // always save the current screenshot for inspection
-  mkdirSync(currentDir, { recursive: true })
-  writeFileSync(resolve(currentDir, fileName), screenshot)
-
-  // @ts-expect-error - this is reliable way of reading Vitest "update" flag
-  const updating = expect.getState().snapshotState?._updateSnapshot === 'all'
-  if (updating || !existsSync(baselinePath)) {
-    // save new baseline screenshot
-    mkdirSync(baselineDir, { recursive: true })
-    writeFileSync(baselinePath, screenshot)
-    return true
-  }
-
-  // compare against stored baseline PNG using pixelmatch
-  const baseline = readFileSync(baselinePath)
-  const baselineImg = decode(baseline)
-  const actualImg = decode(screenshot)
-  const { width, height } = baselineImg
-
-  if (actualImg.width !== width || actualImg.height !== height) {
-    expect.fail(`Screenshot size mismatch: expected ${width}x${height}, got ${actualImg.width}x${actualImg.height}. Actual saved to: ${resolve(currentDir, fileName)}`)
-  }
-
-  const diffCount = pixelmatch(toRGBA(baselineImg), toRGBA(actualImg), undefined, width, height, {
-    threshold: options?.threshold ?? 0.1,
-  })
-
-  const totalPixels = width * height
-  const maxAllowed = options?.maxDiffPixels ?? Math.ceil(totalPixels * (options?.maxDiffPixelRatio ?? 0))
-
-  if (diffCount > maxAllowed) {
-    const ratio = (diffCount / totalPixels * 100).toFixed(2)
-    expect.fail(`Screenshot mismatch: ${diffCount} pixels differ (${ratio}%), allowed ${maxAllowed}. Actual saved to: ${resolve(currentDir, fileName)}`)
-  }
-
-  return true
-}
-
-// helper for bridging difference between Vitest PNG saving and fast-png encoding
-function toRGBA(img: DecodedPng): Uint8Array {
-  const { width, height, data, channels = 4 } = img
-  if (channels === 4) return data as Uint8Array
-  const pixels = width * height
-  const rgba = new Uint8Array(pixels * 4)
-  for (let i = 0; i < pixels; i++) {
-    rgba[i * 4] = data[i * 3]
-    rgba[i * 4 + 1] = data[i * 3 + 1]
-    rgba[i * 4 + 2] = data[i * 3 + 2]
-    rgba[i * 4 + 3] = 255
-  }
-  return rgba
-}
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { decode } from 'fast-png'
+import { expect } from 'vitest'
+import { appendToReport, ensureReportCreated, resolveWithin, screenshotSetup, toRGBA } from './screenshot/report-utils'
+import pixelmatch from 'pixelmatch'
+import type { NuxtPage } from '@nuxt/test-utils'
+
+export interface CompareScreenshotOptions {
+  /** Name of the PNG file used for baseline storage and comparison (defaults to route and `index.png` for `/`) */
+  fileName?: string
+  /** Directory for baseline/current screenshots, relative to project root (defaults to `test/e2e`) */
+  targetDir?: string
+  /** CSS selector for a specific element to capture (defaults to full page) */
+  selector?: string
+  /** Max ratio of different pixels (0–1). Default: 0 (exact match) */
+  maxDiffPixelRatio?: number
+  /** Max absolute number of different pixels. Takes precedence over `maxDiffPixelRatio` when set. Default: 0 (exact match) */
+  maxDiffPixels?: number
+  /** Per-pixel color distance threshold (0–1). Lower = stricter. Default: 0.1 */
+  threshold?: number
+}
+
+// capture a browser screenshot and compare it against a stored baseline PNG
+export async function compareScreenshot(page: NuxtPage, options?: CompareScreenshotOptions): Promise<boolean> {
+  const root = process.cwd()
+
+  // ensure the target directory stays within the project root
+  const dir = resolveWithin(root, options?.targetDir ?? 'test/e2e')
+
+  // create report file on first call
+  ensureReportCreated(dir)
+
+  const baselineDir = resolve(dir, '__baseline__')
+  const currentDir = resolve(dir, '__current__')
+
+  const route = page.url().substring(page.url().lastIndexOf('/') + 1) || 'index'
+  const fileName = options?.fileName ?? `${route}.png`
+
+  // warning on custom non-png file extensions
+  if (!fileName.toLowerCase().endsWith('.png')) {
+    console.warn(`Screenshots from \`compareScreenshot\` are always saved as PNG. Consider different file name than '${fileName}'.`)
+  }
+
+  // ensure the file name cannot escape its target directory
+  const baselinePath = resolveWithin(baselineDir, fileName)
+  const currentPath = resolveWithin(currentDir, fileName)
+
+  // capture element specified by locator or a full-page screenshot as PNG
+  const screenshot = options?.selector
+    ? await page.locator(options.selector).screenshot()
+    : await page.screenshot({ fullPage: true })
+
+  // always save the current screenshot for inspection
+  mkdirSync(currentDir, { recursive: true })
+  writeFileSync(currentPath, screenshot)
+
+  // @ts-expect-error - this is reliable way of reading Vitest "update" flag
+  const updating = expect.getState().snapshotState?._updateSnapshot === 'all'
+  if (updating || !existsSync(baselinePath)) {
+    // save new baseline screenshot
+    mkdirSync(baselineDir, { recursive: true })
+    writeFileSync(baselinePath, screenshot)
+    return true
+  }
+
+  // compare against stored baseline PNG using pixelmatch
+  const baseline = readFileSync(baselinePath)
+  const baselineImg = decode(baseline)
+  const actualImg = decode(screenshot)
+  const { width, height } = baselineImg
+
+  if (actualImg.width !== width || actualImg.height !== height) {
+    const message = `Screenshot size mismatch: expected ${width}x${height}, got ${actualImg.width}x${actualImg.height}. Actual saved to: ${currentPath}`
+    appendToReport(fileName, message, baseline, screenshot)
+    expect.fail(message)
+  }
+
+  const diffCount = pixelmatch(toRGBA(baselineImg), toRGBA(actualImg), undefined, width, height, {
+    threshold: options?.threshold ?? 0.1,
+  })
+
+  const totalPixels = width * height
+  const maxAllowed = options?.maxDiffPixels ?? Math.ceil(totalPixels * (options?.maxDiffPixelRatio ?? 0))
+
+  if (diffCount > maxAllowed) {
+    const ratio = (diffCount / totalPixels * 100).toFixed(2)
+    const message = `Screenshot mismatch: ${diffCount} pixels differ (${ratio}%), allowed ${maxAllowed}. Actual saved to: ${currentPath}`
+    appendToReport(fileName, message, baseline, screenshot)
+    expect.fail(message)
+  }
+
+  return true
+}
+
+// Vitest globalSetup entry point
+// - computes stable timestamp values and exposes them via env variables
+// - the report file itself is created lazily on first compareScreenshot call
+// - provides a callback to close the HTML report once tests are finished (if it was created)
+export default function setup() {
+  // the function itself is defined in the helper file
+  // to avoid imports here and there
+  return screenshotSetup()
+}