nuxt-spec 0.2.2 → 0.2.4-alpha

package/README.md

@@ -38,10 +38,12 @@ If you don't want to use the CLI tool, or you want to understand its flow better
 **1)** - Add following dependency into your `package.json`:
 
 ```json
-"nuxt-spec": "0.2.2"
+"nuxt-spec": "0.2.4-alpha"
 ```
 
-**2** - Add following section into your `nuxt.config.ts`:
+It is advised to remove explicit `nuxt`, `vue` and `vue-router` dependencies, if present. The `nuxt-spec` layer brings them and there might be version clashes if defined in both places.
+
+**2)** - Add following section into your `nuxt.config.ts`:
 
 ```ts
 extends: [
@@ -49,13 +51,13 @@ extends: [
 ]
 ```
 
-**3)** - Add `pnpm-workspace.yaml` file with following content (if you don't have it yet):
+**3)** - If `pnpm` is used, add `pnpm-workspace.yaml` file with following content (if you don't have it yet):
 
 ```yaml
 shamefullyHoist: true
 ```
 
-1) Add `vitest.config.ts` file with following content (if you don't have it yet):
+**4)** Add `vitest.config.ts` file with following content (if you don't have it yet):
 
 ```ts
 import { loadVitestConfig } from 'nuxt-spec/config'
@@ -65,7 +67,13 @@ export default loadVitestConfig({
 })
 ```
 
-**4)** - (Optional) Add following scripts into your `package.json`:
+**5)** Add `.nuxtrc` file with following content (if you don't have it yet):
+
+```text
+setups.@nuxt/test-utils="4.0.3"
+```
+
+**6)** - (Optional) Add following scripts into your `package.json`:
 
 ```json
 "scripts": {
@@ -75,7 +83,7 @@ export default loadVitestConfig({
 }
 ```
 
-**5)** - (Optional) Setup file structures for tests as follows:
+**7)** - (Optional) Setup file structures for tests as follows:
 
 ```text
 test/
@@ -90,7 +98,7 @@ test/
     └── vitest-unit.test.ts
 ```
 
-You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.2.2/test).
+You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.2.4-alpha/test).
 
 ### Install and execute
 
@@ -98,6 +106,8 @@ Whether you used the CLI tool or did the manual setup, you are ready to install
 
 **1)** -  Install the dependencies:
 
+It is advised to remove `node_modules` and delete lock file first. Then proceed with fresh installation.
+
 <!-- tabs:start -->
 
 #### Install using **npm**
@@ -253,11 +263,11 @@ Planned future development:
 - reason about (not) using Vitest browser mode (or make it optional)
 - solution for visual regression testing - (currently there is experimental custom solution)
 
-See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.2/CHANGELOG.md) for the latest updates and features.
+See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.4-alpha/CHANGELOG.md) for the latest updates and features.
 
 ## Configuration
 
-By default, `nuxt-spec` uses Vitest configuration defined in [`/config/index.mjs`](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.2/config/index.mjs). The configuration is based on [Nuxt team recommendations](https://nuxt.com/docs/4.x/getting-started/testing) and our best judgement.
+By default, `nuxt-spec` uses Vitest configuration defined in [`/config/index.mjs`](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.4-alpha/config/index.mjs). The configuration is based on [Nuxt team recommendations](https://nuxt.com/docs/4.x/getting-started/testing) and our best judgement.
 
 To add/override your custom config, you can create (or scaffold via CLI tool) a file named `vitest.config.ts` in the root of your project with the following content:
 
@@ -305,6 +315,14 @@ export default loadVitestConfig({
 
 Alternatively, if you don't want to use any part of the `nuxt-spec` default configuration at all, you can override `vitest.config.ts` file completely and define your own [Vitest configuration](https://vitest.dev/config/) from scratch.
 
+### Filtering out log messages
+
+Some tedious and unrelevant log messages may keep appearing in running tests creating noise and hiding the real issues.
+
+Via `NUXT_SPEC_MESSAGE_FILTERS` env variable you may pass a comma-separated list of (plain) text patterns that should be omited.
+
+It only applies to logs processed by `vitest` though, so some messages might still prevail.
+
 ## Utilities
 
 Nuxt Spec offers a couple of utility functions that are exported via `nuxt-spec/utils` subpackage.
@@ -362,7 +380,9 @@ const html: string = await getAPIResultHtml('/', '#api-fetch', '/your-api', '#ap
 const html: string = await getAPIResultHtml(page, '#api-fetch', '/your-api', '#api-result')
 ```
 
-For detailed description, see [utils.d.ts](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.2/utils/index.d.ts).
+For detailed description, see [utils.d.ts](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.4-alpha/utils/index.d.ts).
+
+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).
 
 ## Contact
 

package/bin/prepublish-check.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { createInterface } from 'node:readline'
+
+const rl = createInterface({ input: process.stdin, output: process.stdout })
+
+rl.question('Are you sure the current solution was properly tested and verified? (y/n) ', (answer) => {
+  rl.close()
+  if (answer.trim().toLowerCase().startsWith('y')) {
+    console.log('Proceeding with publish...')
+    process.exit(0)
+  } else {
+    console.error('Publish aborted. Please run the tests and try again.')
+    process.exit(1)
+  }
+})

package/bin/setup.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { execSync } from 'node:child_process'
 import {
   createFileFromWebTemplate, deletePath, getPackageManager, hasJsonKey,
   pathExists, promptUser, removeFromJsonFile, showMessage,
@@ -16,9 +17,11 @@ import {
  *  2) adds `extends: ['nuxt-spec']` to `nuxt.config.ts`
  *  3) creates/updates `pnpm-workspace.yaml` file (only if pnpm is used)
  *  4) creates default `vitest.config.ts` file
- *  5) adds test-related scripts and pnpm approved build scripts (if using pnpm) in `package.json`
- *  6) creates sample test files
- *  7) clear node_modules and lock file(s)
+ *  5) creates default `.nuxtrc` file
+ *  6) adds test-related scripts in `package.json`
+ *  7) creates sample test files
+ *  8) clear node_modules and lock file(s)
+ *  9) run install command
  *
  * @param {boolean} autoRun - Whether to run the setup automatically without any prompts (defaults to false).
  */
@@ -37,7 +40,7 @@ export async function specSetup(autoRun = false) {
   // add nuxt-spec
   try {
     await updateJsonFile('package.json', 'dependencies', {
-      'nuxt-spec': '0.2.2',
+      'nuxt-spec': '0.2.4-alpha',
     }, isAutoRun, 'This will add \'nuxt-spec\' dependency to your \'package.json\'. Continue?')
   } catch (error) {
     console.error('Error adding \'nuxt-spec\' dependency:\n', error.message)
@@ -107,7 +110,7 @@ export async function specSetup(autoRun = false) {
       if (pathExists('pnpm-workspace.yaml')) {
         await updateTextFile('pnpm-workspace.yaml', ['shamefully-hoist: true'], isAutoRun, 'This will adjust \'pnpm-workspace.yaml\' file in your project. Continue?')
       } else {
-        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.2/config/templates/pnpm-workspace.yaml.template',
+        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.4-alpha/config/templates/pnpm-workspace.yaml.template',
           'pnpm-workspace.yaml', isAutoRun, 'This will add \'pnpm-workspace.yaml\' file for your project. Continue?')
       }
     } catch (error) {
@@ -117,15 +120,22 @@ export async function specSetup(autoRun = false) {
 
   // 4) create vitest.config.ts
   try {
-    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.2/config/templates/vitest.config.ts.template',
+    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.4-alpha/config/templates/vitest.config.ts.template',
       'vitest.config.ts', isAutoRun, 'This will create a new \'vitest.config.ts\' file for your project. Continue?')
   } catch (error) {
     console.error('Error setting up \'vitest.config.ts\':\n', error.message)
   }
 
-  // 5) modify package.json
+  // 5) create .nuxtrc to prevent @nuxt/test-utils setup from running automatically on first start
+  if (!pathExists('.nuxtrc')) {
+    try {
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.4-alpha/.nuxtrc', '.nuxtrc', isAutoRun, 'This will create a \'.nuxtrc\' file to prevent @nuxt/test-utils setup from running automatically when dev server starts. Continue?')
+    } catch (error) {
+      console.error('Error creating \'.nuxtrc\':\n', error.message)
+    }
+  }
 
-  // add test scripts
+  // 6) modify package.json with test scripts
   try {
     await updateJsonFile('package.json', 'scripts', {
       'test': 'vitest run',
@@ -136,57 +146,42 @@ export async function specSetup(autoRun = false) {
     console.error('Error adjusting scripts in \'package.json\':\n', error.message)
   }
 
-  // add pnpm approved build scripts
-  if (packageManager === 'pnpm') {
-    try {
-      await updateJsonFile('package.json', 'pnpm', {
-        onlyBuiltDependencies: [
-          '@parcel/watcher',
-          'esbuild',
-          'unrs-resolver',
-        ],
-      }, isAutoRun, 'This will adjust pnpm approved build scripts in your \'package.json\'. Continue?')
-    } catch (error) {
-      console.error('Error adjusting pnpm approved build scripts in \'package.json\':\n', error.message)
-    }
-  }
-
-  // 6) create sample test files
+  // 7) create sample test files
   const createSampleTests = isAutoRun || await promptUser('Do you want to create sample tests in \'/test\' folder?')
   if (createSampleTests) {
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.2/test/browser/vitest-browser.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.4-alpha/test/browser/vitest-browser.test.ts',
         'test/browser/vitest-browser.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'vitest-browser.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.2/test/e2e/nuxt-e2e.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.4-alpha/test/e2e/nuxt-e2e.test.ts',
         'test/e2e/nuxt-e2e.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'nuxt-e2e.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.2/test/e2e/nuxt-visual.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.4-alpha/test/e2e/nuxt-visual.test.ts',
         'test/e2e/nuxt-visual.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'nuxt-visual.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.2/test/nuxt/nuxt-unit.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.4-alpha/test/nuxt/nuxt-unit.test.ts',
         'test/nuxt/nuxt-unit.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'nuxt-unit.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.2/test/unit/vitest-unit.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.4-alpha/test/unit/vitest-unit.test.ts',
         'test/unit/vitest-unit.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'vitest-unit.test.ts\':\n', error.message)
     }
   }
 
-  // 7) clear node_modules and lock file(s)
+  // 8) clear node_modules and lock file(s)
   const prepareForReinstall = isAutoRun || await promptUser('Dependencies should be re-installed now. Do you want to remove node_modules and the lock file?')
   if (prepareForReinstall) {
     if (pathExists('node_modules')) {
@@ -233,10 +228,23 @@ export async function specSetup(autoRun = false) {
     }
   }
 
-  // 7) inform user
+  // 9) run install command
+  const runInstall = isAutoRun || await promptUser(`Fresh \`${packageManager} install\` is required. Do you want to run it now?`)
+  if (runInstall) {
+    try {
+      showMessage(`Running \`${packageManager} install\`...`)
+      execSync(`${packageManager} install`, { stdio: 'inherit' })
+    } catch (error) {
+      console.error(`Error running \`${packageManager} install\`:\n`, error.message)
+    }
+  }
+
+  // 10) inform user
   showMessage('')
   showMessage('NUXT SPEC SETUP COMPLETE', 2)
-  showMessage(`Proceed with \`${packageManager} install\` to get started.`)
+  if (!runInstall) {
+    showMessage(`Proceed with \`${packageManager} install\` to get started.`)
+  }
 
   // force exit to prevent #20
   process.exit(0)

package/config/index.mjs

@@ -2,6 +2,7 @@
 // based on https://nuxt.com/docs/4.x/getting-started/testing#setup
 // `projects=false` can be used to suspend the default usage of "projects" in Vitest config
 
+import { fileURLToPath } from 'node:url'
 import { onConsoleLog } from './utils/warnings.mjs' // filter out unnecessary logs
 import { mergeConfig } from './utils/merge.mjs' // defu-based merge function
 import { defineConfig } from 'vitest/config'
@@ -9,6 +10,9 @@ import { defineVitestProject } from '@nuxt/test-utils/config'
 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))
+
 export async function loadVitestConfig(userVitestConfig, projects = true) {
   const baseConfig = {
     test: {
@@ -51,6 +55,8 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
           name: 'e2e',
           include: ['test/e2e/**/*.{test,spec}.ts'],
           environment: 'node',
+          // create report file for visual regression testing
+          globalSetup: [screenshotReportSetup],
         },
       },
       // proposed setup for browser component tests (with Playwright runner)

package/config/utils/warnings.mjs

@@ -1,12 +1,13 @@
 const messageFilters = [
-  // remove once @nuxt/test-utils starts depending on Vitest 4.1
-  // https://github.com/nuxt/test-utils/pull/1620
-  'Importing from "vitest/environments" is deprecated',
   // Node+Windows false positive
   // https://github.com/nuxt/icon/issues/140
   'Use of deprecated trailing slash pattern mapping',
   // remove once Vue stops considering <Suspense> experimental
   '<Suspense> is an experimental feature',
+  // merge defaults with user-defined filters from NUXT_SPEC_MESSAGE_FILTERS env variable
+  ...(process.env.NUXT_SPEC_MESSAGE_FILTERS
+    ? process.env.NUXT_SPEC_MESSAGE_FILTERS.split(',')
+    : []),
 ]
 
 // 1) filter-out unnecessary stderr/stdout logs coming from Vitest

package/nuxt.config.ts

@@ -9,7 +9,7 @@ export default defineNuxtConfig({
     dirs: [{ path: '~/components', ignore: ['index.ts'] }],
   },
 
-  compatibilityDate: '2026-05-01',
+  compatibilityDate: '2026-06-01',
 
   eslint: {
     config: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.2.2",
+  "version": "0.2.4-alpha",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": {
     "type": "git",
@@ -9,6 +9,19 @@
   "license": "MIT",
   "type": "module",
   "main": "./nuxt.config.ts",
+  "scripts": {
+    "analyze": "nuxt analyze",
+    "eslint": "eslint .",
+    "build": "pnpm test && nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "prepublishOnly": "node bin/prepublish-check.js",
+    "preview": "nuxt preview",
+    "start": "nuxt start",
+    "test": "vitest run",
+    "test-u": "vitest run -u",
+    "test-i": "vitest"
+  },
   "bin": {
     "nuxt-spec": "bin/cli.js"
   },
@@ -38,35 +51,24 @@
     "nuxt.config.ts"
   ],
   "dependencies": {
-    "@nuxt/eslint": "1.15.2",
-    "@nuxt/test-utils": "4.0.2",
-    "@vitejs/plugin-vue": "6.0.6",
-    "@vitest/browser": "4.1.5",
-    "@vitest/browser-playwright": "4.1.5",
-    "@vitest/ui": "4.1.5",
-    "@vue/test-utils": "2.4.8",
-    "elrh-cosca": "0.3.5",
-    "fast-png": "8.0.0",
-    "happy-dom": "20.9.0",
-    "nuxt": "4.4.2",
-    "pixelmatch": "7.1.0",
-    "playwright-core": "1.59.1",
-    "typescript": "6.0.3",
-    "vitest": "4.1.5",
+    "@nuxt/eslint": "~1.16.0",
+    "@nuxt/test-utils": "4.0.3",
+    "@vitejs/plugin-vue": "~6.0.7",
+    "@vitest/browser": "4.1.9",
+    "@vitest/browser-playwright": "4.1.9",
+    "@vitest/ui": "4.1.9",
+    "@vue/test-utils": "2.4.11",
+    "elrh-cosca": "0.3.6",
+    "fast-png": "~8.0.0",
+    "happy-dom": "~20.10.6",
+    "nuxt": "4.4.8",
+    "pixelmatch": "~7.2.0",
+    "playwright-core": "~1.61.1",
+    "typescript": "~6.0.3",
+    "vitest": "4.1.9",
     "vitest-browser-vue": "2.1.0",
-    "vue": "3.5.33",
-    "vue-router": "5.0.6"
+    "vue": "~3.5.39",
+    "vue-router": "~5.1.0"
   },
-  "scripts": {
-    "analyze": "nuxt analyze",
-    "eslint": "eslint .",
-    "build": "pnpm test && nuxt build",
-    "dev": "nuxt dev",
-    "generate": "nuxt generate",
-    "preview": "nuxt preview",
-    "start": "nuxt start",
-    "test": "vitest run",
-    "test-u": "vitest run -u",
-    "test-i": "vitest"
-  }
-}
+  "packageManager": "pnpm@11.9.0"
+}

package/utils/html/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/html/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/html/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/index.ts

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

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

@@ -1,7 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { expect } from 'vitest'
+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'
 
@@ -22,22 +24,37 @@ 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> {
-  const dir = resolve(process.cwd(), options?.targetDir ?? 'test/e2e')
+  // 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 })
-  const baselinePath = resolve(baselineDir, fileName)
 
   // always save the current screenshot for inspection
   mkdirSync(currentDir, { recursive: true })
-  writeFileSync(resolve(currentDir, fileName), screenshot)
+  writeFileSync(currentPath, screenshot)
 
   // @ts-expect-error - this is reliable way of reading Vitest "update" flag
   const updating = expect.getState().snapshotState?._updateSnapshot === 'all'
@@ -55,7 +72,9 @@ export async function compareScreenshot(page: NuxtPage, options?: CompareScreens
   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 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, {
@@ -67,12 +86,55 @@ export async function compareScreenshot(page: NuxtPage, options?: CompareScreens
 
   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)}`)
+    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

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')
+  }
+}