nuxt-spec 0.2.3 → 0.2.4-alpha

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-compare'
+import type { CompareScreenshotOptions } from './screenshot-compare'
+
+export {
+  compareScreenshot,
+  gotoPage,
+  getDataHtml,
+  getAPIResultHtml,
+}
+
+export type { CompareScreenshotOptions }

package/utils/{screenshot.ts → screenshot-compare.ts}

@@ -1,89 +1,151 @@
-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 { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { decode, type DecodedPng } from 'fast-png'
+import { expect } from 'vitest'
+import { ensureReportCreated, getInjection } from './screenshot-report'
+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> {
+  // create report file on first call
+  ensureReportCreated()
+
+  const root = process.cwd()
+
+  // ensure the target directory stays within the project root
+  const dir = resolveWithin(root, 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`
+
+  // 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
+}
+
+// helper to make sure passed options are not escaping from cwd
+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
+}
+
+// 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))
+}
+
+const HTML_DIR = resolve(fileURLToPath(import.meta.url), '..', 'html')
+const REPORT_ENTRY = readFileSync(resolve(HTML_DIR, 'report-entry.html'), 'utf-8')
+
+// template for screenshot comparison entry
+// append a side-by-side baseline/actual comparison entry to the HTML report
+function appendToReport(fileName: string, message: string, baseline: Uint8Array, actual: Uint8Array): void {
+  const reportPath = getInjection('screenshotReportPath')
+  if (!reportPath || !existsSync(reportPath)) return
+
+  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)
+
+  appendFileSync(reportPath, entry)
+}
+
+// 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
+}

package/utils/screenshot-report.ts

@@ -0,0 +1,116 @@
+import { exec } from 'node:child_process'
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { inject } from 'vitest'
+import type { ProvidedContext } from 'vitest'
+import type { TestProject } from 'vitest/node'
+
+declare module 'vitest' {
+  interface ProvidedContext {
+    screenshotReportPath: string
+    screenshotReportTitle: string
+  }
+}
+
+const templatesDir = resolve(fileURLToPath(import.meta.url), '..', 'html')
+
+// 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('')
+}
+
+// read the header template and replace the timestamp placeholder
+function reportScaffold(titleTimestamp: string): string {
+  const template = readFileSync(resolve(templatesDir, 'report-head.html'), 'utf-8')
+  return template.replace('{{TIMESTAMP}}', titleTimestamp)
+}
+
+// resolve the value created in the Vitest globalSetup helper
+// (provide/inject is preferred, with process.env kept as a fallback)
+export function getInjection(key: keyof ProvidedContext): string | undefined {
+  try {
+    const injected = inject(key)
+    if (injected) return injected
+  } catch (e) {
+    // `inject` is unavailable outside of the Vitest worker context
+    console.debug(`(nuxt-spec) getInjection(${key}) - error during Vitest injection`)
+    console.error((e as Error).message || e)
+  }
+
+  console.debug(`(nuxt-spec) getInjection(${key}) - falling back to process.env`)
+
+  // env variable fallbacks
+  switch (key) {
+    case 'screenshotReportPath':
+      return process.env.SCREENSHOT_REPORT_PATH
+    case 'screenshotReportTitle':
+      return process.env.SCREENSHOT_REPORT_TITLE
+    default:
+      return undefined
+  }
+}
+
+// create report file on first call, using the path computed in setup()
+export function ensureReportCreated(): void {
+  const reportPath = getInjection('screenshotReportPath')
+  if (!reportPath || existsSync(reportPath)) return
+
+  const titleTimestamp = getInjection('screenshotReportTitle') ?? reportTimestamp(new Date(), true)
+
+  writeFileSync(reportPath, reportScaffold(titleTimestamp))
+}
+
+// Vitest globalSetup entry point
+// - computes the report path and exposes it via provide/inject
+// - the report file is created lazily on first compareScreenshot call
+// - closes the HTML report via a callback once tests are finished (if it was created)
+export default function setup({ provide }: TestProject) {
+  const dir = resolve(process.cwd(), 'test/e2e', '__current__')
+  mkdirSync(dir, { recursive: true })
+
+  const NOW = new Date()
+  const reportPath = resolve(dir, `report-${reportTimestamp(NOW)}.html`)
+  provide('screenshotReportPath', reportPath)
+  provide('screenshotReportTitle', reportTimestamp(NOW, true))
+
+  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')
+  }
+}