nuxt-spec 0.3.3 → 0.4.0-alpha.1

package/utils/screenshot.ts

@@ -1,13 +1,33 @@
 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 { expect, recordArtifact, TestRunner } from 'vitest'
+import type { TestArtifactBase, TestAttachment } from 'vitest'
+import { resolveWithin, toRGBA } from './helpers/screenshot-utils'
 import pixelmatch from 'pixelmatch'
 import type { GotoOptions, NuxtPage } from '@nuxt/test-utils'
 import { checkNumberParam, checkPageParam, checkStringParam } from './helpers/check-params'
 import { gotoPage } from './e2e'
 
+/**
+ * Test artifact recorded by `compareScreenshot()` on mismatch.
+ * It is consumed by the Nuxt Spec HTML reporter.
+ */
+export interface NuxtSpecScreenshotArtifact extends TestArtifactBase {
+  type: 'nuxt-spec:screenshot'
+  /** Name of the compared PNG file */
+  fileName: string
+  /** Description of the mismatch */
+  message: string
+  attachments: Array<TestAttachment & { name: 'baseline' | 'actual' }>
+}
+
+declare module 'vitest' {
+  interface TestArtifactRegistry {
+    'nuxt-spec:screenshot': NuxtSpecScreenshotArtifact
+  }
+}
+
 /**
  * Extra settings object for `compareScreenshot()` function.
  * All properties are optional.
@@ -87,16 +107,13 @@ export async function compareScreenshot(page: NuxtPage | string, options?: Compa
   const currentDir = resolve(dir, '__current__')
   mkdirSync(currentDir, { recursive: true })
 
-  // create report file on first call
-  ensureReportCreated(dir)
-
   // compute screenshot file name
   const route = pageInstance.url().substring(pageInstance.url().lastIndexOf('/') + 1) || 'index'
   const screenshotFile = fileName ?? `${route}.png`
 
   // warning on custom non-png file extensions
   if (!screenshotFile.toLowerCase().endsWith('.png')) {
-    console.warn(`Screenshots from \`compareScreenshot\` are always saved as PNG. Consider different file name than '${screenshotFile}'.`)
+    console.warn(`[Nuxt Spec] Screenshots from \`compareScreenshot\` are always saved as PNG. Consider different file name than '${screenshotFile}'.`)
   }
 
   // ensure the file name cannot escape its target directory
@@ -134,7 +151,7 @@ export async function compareScreenshot(page: NuxtPage | string, options?: Compa
     }
     // otherwise report failure
     const message = `Screenshot size mismatch: expected ${width}x${height}, got ${actualImg.width}x${actualImg.height}. Actual saved to: ${currentPath}`
-    appendToReport(screenshotFile, message, baseline, screenshot)
+    await reportMismatch(screenshotFile, message, baseline, screenshot)
     expect.fail(message)
   }
 
@@ -154,19 +171,31 @@ export async function compareScreenshot(page: NuxtPage | string, options?: Compa
     // otherwise report failure
     const ratio = (diffCount / totalPixels * 100).toFixed(2)
     const message = `Screenshot mismatch: ${diffCount} pixels differ (${ratio}%), allowed ${maxAllowed}. Actual saved to: ${currentPath}`
-    appendToReport(screenshotFile, message, baseline, screenshot)
+    await reportMismatch(screenshotFile, 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()
+// pass the baseline/actual pair to the Nuxt Spec HTML reporter via Vitest test artifacts
+// best-effort only - it must never mask the actual assertion failure
+async function reportMismatch(fileName: string, message: string, baseline: Uint8Array, actual: Uint8Array): Promise<void> {
+  // undefined when called outside of a running test (e.g. in `beforeAll`)
+  const test = TestRunner.getCurrentTest()
+  if (!test) return
+
+  try {
+    await recordArtifact(test, {
+      type: 'nuxt-spec:screenshot',
+      fileName,
+      message,
+      attachments: [
+        { name: 'baseline', contentType: 'image/png', body: baseline },
+        { name: 'actual', contentType: 'image/png', body: actual },
+      ],
+    })
+  } catch {
+    // reporting is optional
+  }
 }

package/utils/screenshot/report-head.html

@@ -1,24 +0,0 @@
-<!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

@@ -1,4 +0,0 @@
-<!-- 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

@@ -1,236 +0,0 @@
-import { exec } from 'node:child_process'
-import { appendFileSync, existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
-import { platform } from 'node:os'
-import { resolve, sep } from 'node:path'
-import { fileURLToPath, pathToFileURL } 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(), '.nuxt/.nuxt-spec-report-path')
-const REPORT_LOCK = resolve(process.cwd(), '.nuxt/.nuxt-spec-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(targetDir)) {
-      throw new Error(`Target directory "${targetDir}" does not exist.`)
-    }
-
-    if (existsSync(REPORT_PATH)) {
-      // report file was already created
-      reportPath = readFileSync(REPORT_PATH, 'utf-8').trim()
-      // this shouldn't happen...
-      if (!existsSync(reportPath)) {
-        throw new Error(`Invalid data in "${REPORT_PATH}": Report file "${reportPath}" does not exist.`)
-      }
-    } else {
-      // for the first time, prepare and store new time-stamped file path
-      const fileTimestamp = process.env.SCREENSHOT_REPORT_TIMESTAMP ?? reportTimestamp(new Date())
-      reportPath = resolve(targetDir, '__current__', `report-${fileTimestamp}.html`)
-      writeFileSync(REPORT_PATH, reportPath)
-    }
-
-    // store the path for `appendToReport`
-    process.env.SCREENSHOT_REPORT_PATH = reportPath
-
-    // report file was already created
-    if (existsSync(reportPath)) return
-
-    // create new report file from template
-    const titleTimestamp = process.env.SCREENSHOT_REPORT_TITLE ?? reportTimestamp(new Date(), 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
-
-  // callback that is executed upon Vitest teardown phase
-  return () => {
-    if (!existsSync(REPORT_PATH)) return
-
-    const reportPath = readFileSync(REPORT_PATH, 'utf-8').trim()
-    unlinkSync(REPORT_PATH)
-
-    if (!reportPath) return
-    if (!existsSync(reportPath)) return
-
-    // add "success" / "error" message as a conclusion
-    const reportBody = readFileSync(reportPath, 'utf-8')
-    const hasFailure = reportBody.includes('<div class="failure"')
-    if (hasFailure) {
-      appendFileSync(reportPath, '<p style="color: #b00; font-weight: 700; font-size: 18px;">Tests finished with errors</p>\n')
-    } else {
-      appendFileSync(reportPath, '<p style="color: #0b0; font-weight: 700; font-size: 18px;">All tests have passed</p>\n')
-    }
-
-    // wrap the report up with a footer
-    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:\n${pathToFileURL(reportPath).href}`)
-
-    if (!process.env.CI) {
-      console.log('(nuxt-spec) Opening report in default browser...')
-      const openCmd
-        = platform() === 'darwin'
-          ? `open "${reportPath}"`
-          : platform() === 'win32'
-            ? `start "" "${reportPath}"`
-            : `xdg-open "${reportPath}"`
-      exec(openCmd, (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++) {
-    const src = i * 3
-    rgba[i * 4 + 0] = data[src + 0] ?? 0
-    rgba[i * 4 + 1] = data[src + 1] ?? 0
-    rgba[i * 4 + 2] = data[src + 2] ?? 0
-    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))
-}