nuxt-spec 0.2.4-alpha → 0.2.4-alpha.3

package/README.md

@@ -384,6 +384,30 @@ For detailed description, see [utils.d.ts](https://github.com/AloisSeckar/nuxt-s
 
 The `compareScreenshot` function usage results into HTML report file being automatically created. The file is generated within the specified `__current__` directory as `report_YYYYMMDDHHMMSS.html`. It contains all failed screenshots comparison. When test suite is over, file is attempted to be opened in system default browser (unless Node operates in `CI` mode).
 
+### Notice on non-default setups
+
+The creation of the report file and it's proper wrap-up at the end is ensured via `globalSetup` function passed into default Vitest E2E suite defined by Nuxt Spec. If you need to override the default `e2e` project, you also need to make sure to call the setup function manually.
+
+Add following into your `vitest.config.ts`:
+
+```ts
+// vitest.config.ts
+import { loadVitestConfig } from 'nuxt-spec/config'
+
+// resolve path to Nuxt Spec's setup function
+const screenshotReportSetup = fileURLToPath(new URL('../utils/screenshot.ts', import.meta.resolve('nuxt-spec/config')))
+
+export default loadVitestConfig({
+  // whatever e2e test you are defining
+  test: {
+    // provide it to your `compareScreenshot` using test suite
+    globalSetup: [screenshotReportSetup],
+    // other config
+  },
+  // other config
+})
+```
+
 ## Contact
 
 Use GitHub issues to report bugs or suggest improvements. I will be more than happy to address them.

package/app/components/index.d.ts

@@ -0,0 +1,7 @@
+// type hint for tsconfig.nuxt-spec.json
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}

package/config/index.mjs

@@ -11,7 +11,7 @@ import { playwright } from '@vitest/browser-playwright'
 import vue from '@vitejs/plugin-vue'
 
 // absolute path so it works from nuxt-ignis package
-const screenshotReportSetup = fileURLToPath(new URL('../utils/screenshot-report.ts', import.meta.url))
+const screenshotReportSetup = fileURLToPath(new URL('../utils/screenshot.ts', import.meta.url))
 
 export async function loadVitestConfig(userVitestConfig, projects = true) {
   const baseConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.2.4-alpha",
+  "version": "0.2.4-alpha.3",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": {
     "type": "git",
@@ -12,6 +12,7 @@
   "scripts": {
     "analyze": "nuxt analyze",
     "eslint": "eslint .",
+    "typecheck": "nuxi typecheck",
     "build": "pnpm test && nuxt build",
     "dev": "nuxt dev",
     "generate": "nuxt generate",
@@ -68,7 +69,8 @@
     "vitest": "4.1.9",
     "vitest-browser-vue": "2.1.0",
     "vue": "~3.5.39",
-    "vue-router": "~5.1.0"
+    "vue-router": "~5.1.0",
+    "vue-tsc": "~3.3.6"
   },
   "packageManager": "pnpm@11.9.0"
 }

package/utils/index.ts

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

package/utils/screenshot/report-utils.ts

@@ -0,0 +1,211 @@
+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(), '.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(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++) {
+    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))
+}

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

@@ -1,9 +1,8 @@
-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 { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { decode } from 'fast-png'
 import { expect } from 'vitest'
-import { ensureReportCreated, getInjection } from './screenshot-report'
+import { appendToReport, ensureReportCreated, resolveWithin, screenshotSetup, toRGBA } from './screenshot/report-utils'
 import pixelmatch from 'pixelmatch'
 import type { NuxtPage } from '@nuxt/test-utils'
 
@@ -24,14 +23,14 @@ export interface CompareScreenshotOptions {
 
 // 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')
 
+  // create report file on first call
+  ensureReportCreated(dir)
+
   const baselineDir = resolve(dir, '__baseline__')
   const currentDir = resolve(dir, '__current__')
 
@@ -94,58 +93,12 @@ export async function compareScreenshot(page: NuxtPage, options?: CompareScreens
   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
+// 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()
 }

package/utils/screenshot-report.ts

@@ -1,116 +0,0 @@
-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')
-  }
-}