nuxt-spec 0.1.18 → 0.2.0-alpha.2

package/README.md

@@ -4,7 +4,7 @@
 
 **Nuxt Spec** (aka `nuxt-spec`) is a base layer for [Nuxt](https://nuxt.com/) applications incorporating together a couple of testing libraries and packages and providing some utility functions. I created this project in early 2025 because I was unable to find a convenient "one-dependency" way to start testing my Nuxt apps and I didn't want to repeat the same steps and maintain the same set of dependencies over and over. 
 
-While Nuxt itself does have a [dedicated module for testing](https://nuxt.com/docs/getting-started/testing), to remain as versatile as possible, it has to be combined with other packages (which can be different based on your choice). I am trying to overcome this by defining "the way". This is both the strength and the weakness of this project. You were warned.
+While Nuxt itself does have a [dedicated module for testing](https://nuxt.com/docs/getting-started/testing), to remain as versatile as possible, it has to be combined with other packages (which can be different based on your choice). I am trying to overcome this by defining "The Way". This is both the strength and the weakness of this project. You were warned.
 
 The most important client of `nuxt-spec` is my [Nuxt Ignis](https://github.com/AloisSeckar/nuxt-ignis) template starter that adds up even more ready-to-use cool stuff for your future awesome Nuxt websites.
 
@@ -16,6 +16,7 @@ The `nuxt-spec` package comes with a built-in CLI tool that can help you:
 - setup the dependency in your project
 - scaffold the default `vitest.config.ts` (see [configuration](#configuration) section)
 - add a few test-related script shorthands into your `package.json` (see [running tests](#running-tests) section)
+- create demo test files in proposed file structure
 
 To use it, just run the CLI script in your terminal:
 
@@ -36,7 +37,7 @@ 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`:
 
 ```
-"nuxt-spec": "0.1.18"
+"nuxt-spec": "0.2.0-alpha.2"
 ```
 
 2) Add following section into your `nuxt.config.ts`:
@@ -77,15 +78,18 @@ export default loadVitestConfig({
 
 ```
 test/
+├── browser/
+│   └── vitest-browser.test.ts
 ├── e2e/
 │   └── nuxt-e2e.test.ts
+│   └── nuxt-visual.test.ts
 ├── nuxt/
 │   └── nuxt-unit.test.ts
 └── unit/
-    └── vitest.test.ts
+    └── vitest-unit.test.ts
 ```
 
-You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.1.18/test).
+You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.2.0-alpha.2/test).
 
 ### Install and execute
 
@@ -234,7 +238,8 @@ Or you can use the `vitest` command directly with all its parameters. See [Vites
 
 **Nuxt Spec** currently contains:
 - [vitest](https://www.npmjs.com/package/vitest) **v4** as the fundamental testing framework
-- [@vitest/browser](https://www.npmjs.com/package/@vitest/browser) as the experimental browser runner
+- [@vitest/browser](https://www.npmjs.com/package/@vitest/browser) as more advanced browser-native testing runner
+- [@vitest/ui](https://www.npmjs.com/package/@vitest/ui) as graphic UI above the Vitest test runner
 - [happy-dom](https://www.npmjs.com/package/happy-dom) as the headless browser runtime
 - [playwright-core](https://www.npmjs.com/package/playwright-core) as the headless browser testing framework
 - [@vue/test-utils](https://www.npmjs.com/package/@vue/test-utils) for testing Vue stuff
@@ -242,13 +247,13 @@ Or you can use the `vitest` command directly with all its parameters. See [Vites
 
 Planned future development:
 - reason about (not) using Vitest browser mode (or make it optional)
-- solution for visual testing - either [backstopjs](https://www.npmjs.com/package/backstopjs) or Vitest's native (currently experimental)
+- solution for visual regression testing - (currently there is experimental custom solution)
 
-See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.1.18/CHANGELOG.md) for the latest updates and features.
+See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.2/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.1.18/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.0-alpha.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.
 
 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:
 
@@ -271,16 +276,19 @@ export default loadVitestConfig({
   test: {
     // your custom config specific to Vitest here
   }
+  // by the nature of the Vitest config resolution,
+  // you may also pass ANY OTHER valid Vite configuration options here
 })
 ```
 
-By default, Nuxt Spec built-in configuration establishes 3 `projects` + one fallback:
+By default, Nuxt Spec built-in configuration establishes 4 `projects` + one fallback:
 - `unit` - for unit tests in `test/unit/**` - env is set to `node` 
 - `nuxt` - for Nuxt-related tests in `test/nuxt/**` - env is set to `nuxt` 
 - `e2e` - for end-to-end tests in `test/e2e/**` - env is set to `node` 
+- `browser` - for browser-mode tests in `test/browser/**` - env is set to `node` (this is effectively an alternative to `nuxt` relying on `@vitest/browser` instead of `@nuxt/test-utils`)
 - `default` - fallback for all other tests in `test/**` and/or `tests/**` directories - env is set to `node` 
 
-Vitest will then expects at least one test defined in either of those directories. The `test.projects` confing may be extended with others, but it cannot be easily removed due to nature of defu-merge process. If your project uses different configuration (i.e. your test reside in completely different path), you can pass `false` as a second parameter to `loadVitestConfig()` function to exclude `test.projects` key to be injected:
+Vitest will then expects at least one test defined in either of those directories. Any parts of the `test.projects` confing may be altered and user-defined values will be logically merged with the defaults. Also you may add new custom projects' definitions to fit your needs. If your project uses significantly different configuration (i.e. your tests reside in completely different path), you can pass `false` as a second parameter to `loadVitestConfig()` function to exclude default `test.projects` values from being injected completely:
 
 ```ts
 import { loadVitestConfig } from 'nuxt-spec/config'
@@ -292,6 +300,41 @@ 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.
 
+## Utilities
+
+Nuxt Spec offers couple of utility functions that are exported via `nuxt-spec/utils` subpackage.
+
+You can use them in your test files as follows:
+
+```ts
+import { compareScreenshot, gotoPage, getDataHtml, getAPIResultHtml, } from 'nuxt-spec/utils'
+
+// accepts instance of NuxtPage (from @nuxt/test-utils)
+// takes a screenshot of current viewport and compares it with stored baseline
+// if screenshot doesn't exist, it will be created as baseline
+// if screenshots don't match, the method will cause Vitest test to fail
+await compareScreenshot(page, 'screenshot.png')
+
+// navigates to given URL and returns the instance of NuxtPage (from @nuxt/test-utils)
+const page: NuxtPage = await gotoPage('url')
+
+// accepts either a URL string or instance of NuxtPage (from @nuxt/test-utils) and a CSS selector
+// returns `innerHTML` of the element matching the selector
+const html: string = await getDataHtml('/', '#test') 
+const html: string = await getDataHtml(page, '#test')
+
+// accepts either a URL string or instance of NuxtPage (from @nuxt/test-utils)
+// css selector for element that triggers API call when clicked (i.e. button)
+// fragment of API endpoint URL that should be called (to test the response)
+// css selector for element where the API response should be rendered (i.e. div)
+// returns `innerHTML` of the element matching the result selector after the API call 
+// is made by Playwright runner
+const html: string = await getAPIResultHtml('/', '#api-fetch', '/your-api', '#api-result')
+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.0-alpha.2/utils/index.d.ts).
+
 ## Contact
 
 Use GitHub issues to report bugs or suggest improvements. I will be more than happy to address them.

package/app/app.vue

@@ -4,6 +4,7 @@
     <div>
       Test-pack layer for <a href="https://nuxt.com/">Nuxt</a> applications
     </div>
-    <NuxtSpecTestComponent text="Test Component" />
+    <NuxtSpecTestComponent id="test" text="Test Component" />
+    <NuxtSpecApiTestComponent />
   </div>
 </template>

package/app/components/NuxtSpecApiTestComponent.vue

@@ -0,0 +1,24 @@
+<template>
+  <div>
+    <h2>API Test</h2>
+    <button id="api-fetch" @click="fetchData">
+      Fetch Data
+    </button>
+    <div id="api-result">
+      {{ data }}
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const data = ref('')
+const fetchData = async () => {
+  try {
+    data.value = await $fetch('https://jsonplaceholder.typicode.com/posts/1')
+    console.debug('Fetched data:', data.value)
+  } catch (error) {
+    data.value = 'Error fetching data'
+    console.error('API fetch error:', error)
+  }
+}
+</script>

package/bin/setup.js

@@ -37,7 +37,7 @@ export async function specSetup(autoRun = false) {
   // add nuxt-spec
   try {
     await updateJsonFile('package.json', 'dependencies', {
-      'nuxt-spec': '0.1.18',
+      'nuxt-spec': '0.2.0-alpha.2',
     }, 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 +107,7 @@ export async function specSetup(autoRun = false) {
       if (pathExists('.npmrc')) {
         await updateTextFile('.npmrc', ['shamefully-hoist=true'], isAutoRun, 'This will adjust \'.npmrc\' file in your project. Continue?')
       } else {
-        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.1.18/.npmrc',
+        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/.npmrc',
           '.npmrc', isAutoRun, 'This will add \'.npmrc\' file for your project. Continue?')
       }
     } catch (error) {
@@ -117,7 +117,7 @@ export async function specSetup(autoRun = false) {
 
   // 4) create vitest.config.ts
   try {
-    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.1.18/config/vitest.config.ts.template',
+    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/config/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)
@@ -155,22 +155,34 @@ export async function specSetup(autoRun = false) {
   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.1.18/test/e2e/nuxt-e2e.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/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.0-alpha.2/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.1.18/test/nuxt/nuxt-unit.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/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.0-alpha.2/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.1.18/test/unit/vitest.test.ts',
-        'test/unit/vitest.test.ts', true)
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/test/unit/vitest-unit.test.ts',
+        'test/unit/vitest-unit.test.ts', true)
     } catch (error) {
-      console.error('Error setting up \'vitest.test.ts\':\n', error.message)
+      console.error('Error setting up \'vitest-unit.test.ts\':\n', error.message)
     }
   }
 

package/config/index.mjs

@@ -2,9 +2,11 @@
 // 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 { defu } from 'defu'
+import { mergeConfig } from './merge.js' // defu-based merge function
 import { defineConfig } from 'vitest/config'
 import { defineVitestProject } from '@nuxt/test-utils/config'
+import { playwright } from '@vitest/browser-playwright'
+import vue from '@vitejs/plugin-vue'
 
 export async function loadVitestConfig(userVitestConfig, projects = true) {
   const baseConfig = {
@@ -17,19 +19,19 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
       {
         test: {
           name: 'default',
-          include: ['{test,tests}/**/*.{test,spec}.ts', '!test/{nuxt,e2e,unit}/**'],
+          include: ['{test,tests}/**/*.{test,spec}.ts', '!test/{browser,e2e,nuxt,unit}/**'],
           environment: 'node',
         },
       },
-      // proposed setup for unit and e2e tests
+      // proposed setup for Unit tests
       {
         test: {
           name: 'node',
-          include: ['test/{e2e,unit}/**/*.{test,spec}.ts'],
+          include: ['test/unit/**/*.{test,spec}.ts'],
           environment: 'node',
         },
       },
-      // proposed setup for Nuxt
+      // proposed setup for Nuxt component tests
       await defineVitestProject({
         test: {
           name: 'nuxt',
@@ -37,8 +39,35 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
           environment: 'nuxt',
         },
       }),
+      // proposed setup for classic E2E tests (node-based, using @nuxt/test-utils)
+      {
+        test: {
+          name: 'e2e',
+          include: ['test/e2e/**/*.{test,spec}.ts'],
+          environment: 'node',
+        },
+      },
+      // proposed setup for browser component tests (with Playwright runner)
+      {
+        // vue plugin is required for proper imports resolution
+        plugins: [vue()],
+        test: {
+          name: 'browser',
+          include: ['test/browser/**/*.{test,spec}.ts'],
+          environment: 'node',
+          browser: {
+            provider: playwright(),
+            enabled: true,
+            headless: true,
+            instances: [{
+              browser: 'chromium',
+              viewport: { width: 1280, height: 720 },
+            }],
+          },
+        },
+      },
     ]
   }
 
-  return defu(userVitestConfig, defineConfig(baseConfig))
+  return mergeConfig(userVitestConfig, defineConfig(baseConfig))
 }

package/config/merge.js

@@ -0,0 +1,40 @@
+// custom merger function based on defu
+// allows working with the "projects" array properly
+// user-defined config overrides are merged by "name"
+
+// for consistent and predictable results, passing "include" or "browser.instances"
+// will result into OVERRIDE insteead of merging with nuxt-spec defaults
+
+import { createDefu } from 'defu'
+
+export const mergeConfig = createDefu((obj, key, value) => {
+  if (key === 'projects' && Array.isArray(obj[key]) && Array.isArray(value)) {
+    const defaults = obj[key]
+    const overrides = value
+
+    // override default values if user-defined config specifies them
+    obj[key] = defaults.map((defaultProject) => {
+      const override = overrides.find(o => o.name === defaultProject.name)
+      return override ? mergeProject(override, defaultProject) : defaultProject
+    })
+
+    // add any user projects that don't exist in defaults
+    for (const override of overrides) {
+      if (!defaults.some(d => d.name === override.name)) {
+        obj[key].push(override)
+      }
+    }
+
+    return true
+  }
+})
+
+// Keys where user value should fully replace the default, not merge
+const overrideKeys = new Set(['include', 'instances'])
+
+const mergeProject = createDefu((obj, key, value) => {
+  if (overrideKeys.has(key)) {
+    obj[key] = value
+    return true
+  }
+})

package/nuxt.config.ts

@@ -4,7 +4,7 @@ export default defineNuxtConfig({
     '@nuxt/test-utils/module',
   ],
 
-  compatibilityDate: '2025-12-14',
+  compatibilityDate: '2026-02-22',
 
   eslint: {
     config: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.1.18",
+  "version": "0.2.0-alpha.2",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": "github:AloisSeckar/nuxt-spec",
   "license": "MIT",
@@ -15,27 +15,37 @@
       "types": "./config/index.d.ts",
       "import": "./config/index.mjs",
       "default": "./config/index.mjs"
+    },
+    "./utils": {
+      "types": "./utils/index.d.ts",
+      "import": "./utils/index.ts",
+      "default": "./utils/index.ts"
     }
   },
   "files": [
     "app",
     "bin",
     "config",
-    "public"
+    "public",
+    "utils"
   ],
   "dependencies": {
-    "@nuxt/eslint": "1.14.0",
+    "@nuxt/eslint": "1.15.1",
     "@nuxt/test-utils": "4.0.0",
+    "@vitejs/plugin-vue": "6.0.4",
     "@vitest/browser": "4.0.18",
+    "@vitest/browser-playwright": "4.0.18",
+    "@vitest/ui": "4.0.18",
     "@vue/test-utils": "2.4.6",
     "elrh-cosca": "0.3.5",
-    "happy-dom": "20.5.1",
+    "happy-dom": "20.7.0",
     "nuxt": "4.3.1",
     "playwright-core": "1.58.2",
     "typescript": "5.9.3",
     "vitest": "4.0.18",
-    "vue": "3.5.27",
-    "vue-router": "5.0.2"
+    "vitest-browser-vue": "2.0.2",
+    "vue": "3.5.28",
+    "vue-router": "5.0.3"
   },
   "scripts": {
     "analyze": "nuxt analyze",

package/utils/e2e.ts

@@ -0,0 +1,30 @@
+import { createPage, url } from '@nuxt/test-utils/e2e'
+import type { NuxtPage } from '@nuxt/test-utils'
+
+// visit a specified URL and return the page instance for further interaction
+export async function gotoPage(pageName: string): Promise<NuxtPage> {
+  const page = await createPage()
+  const urlPath = pageName.startsWith('/') ? url(pageName) : url(`/${pageName}`)
+  await page.goto(urlPath, { waitUntil: 'hydration' })
+  return page
+}
+
+// extract HTML content from specified element on a given page
+export async function getDataHtml(page: NuxtPage | string, element: string): Promise<string> {
+  const pageInstance = typeof page === 'string' ? await gotoPage(page) : page
+  const dataDiv = pageInstance.locator(element)
+  return await dataDiv.innerHTML()
+}
+
+// execute an API call and extract HTML content from the result
+// (assumes clickable element that triggers the request
+// and separate element for displaying the response)
+export async function getAPIResultHtml(page: NuxtPage | string, triggerElement: string, targetUrl: string, responseElement: string) {
+  const pageInstance = typeof page === 'string' ? await gotoPage(page) : page
+  await pageInstance.click(triggerElement)
+  await pageInstance.waitForResponse(response =>
+    response.url().includes(targetUrl) && response.ok(),
+  )
+  const resultDiv = pageInstance.locator(responseElement)
+  return await resultDiv.innerHTML()
+}

package/utils/index.d.ts

@@ -0,0 +1,53 @@
+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>
+
+/**
+ * Capture a full-page 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.
+ *
+ * @param page - Playwright page instance obtained from `createPage()`
+ * @param fileName - Name of the PNG file used for baseline storage and comparison
+ * @param targetDir - Directory for baseline/current screenshots, relative to project root (defaults to `test/e2e`)
+ * @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,
+  fileName: string,
+  targetDir?: string,
+): Promise<boolean>

package/utils/index.ts

@@ -0,0 +1,9 @@
+import { gotoPage, getDataHtml, getAPIResultHtml } from './e2e'
+import { compareScreenshot } from './screenshot'
+
+export {
+  compareScreenshot,
+  gotoPage,
+  getDataHtml,
+  getAPIResultHtml,
+}

package/utils/screenshot.ts

@@ -0,0 +1,34 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { NuxtPage } from '@nuxt/test-utils'
+import { expect } from 'vitest'
+
+export async function compareScreenshot(page: NuxtPage, fileName: string, targetDir?: string): Promise<boolean> {
+  const dir = resolve(process.cwd(), targetDir ?? 'test/e2e')
+  const baselineDir = resolve(dir, '__baseline__')
+  const currentDir = resolve(dir, '__current__')
+
+  // capture full-page screenshot as PNG
+  const screenshot = await page.screenshot({ fullPage: true })
+  const baselinePath = resolve(baselineDir, fileName)
+
+  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
+  const baseline = readFileSync(baselinePath)
+  if (!screenshot.equals(baseline)) {
+    // save what the test actually saw for debugging
+    mkdirSync(currentDir, { recursive: true })
+    const actualPath = resolve(currentDir, fileName)
+    writeFileSync(actualPath, screenshot)
+    expect.fail(`Screenshot mismatch. Actual result saved to: ${actualPath}`)
+  }
+
+  return true
+}