nuxt-spec 0.2.3 → 0.2.4-alpha

package/config/index.mjs

@@ -1,79 +1,85 @@
-// this is the default Vitest config object
-// 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 { onConsoleLog } from './utils/warnings.mjs' // filter out unnecessary logs
-import { mergeConfig } from './utils/merge.mjs' // 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 = {
-    test: {
-      // filter-out unnecessary console logs coming from Vitest
-      // when the import is resolved, unnecessary stderr logs are also filtered-out
-      // as a side-effect
-      onConsoleLog,
-    },
-  }
-
-  if (projects === true) {
-    baseConfig.test.projects = [
-      // default fallback to catch tests directly in /test folder
-      {
-        test: {
-          name: 'default',
-          include: ['{test,tests}/**/*.{test,spec}.ts', '!test/{browser,e2e,nuxt,unit}/**'],
-          environment: 'node',
-        },
-      },
-      // proposed setup for Unit tests
-      {
-        test: {
-          name: 'node',
-          include: ['test/unit/**/*.{test,spec}.ts'],
-          environment: 'node',
-        },
-      },
-      // proposed setup for Nuxt component tests
-      await defineVitestProject({
-        test: {
-          name: 'nuxt',
-          include: ['test/nuxt/**/*.{test,spec}.ts'],
-          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 mergeConfig(userVitestConfig, defineConfig(baseConfig))
-}
+// this is the default Vitest config object
+// 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'
+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: {
+      // filter-out unnecessary console logs coming from Vitest
+      // when the import is resolved, unnecessary stderr logs are also filtered-out
+      // as a side-effect
+      onConsoleLog,
+    },
+  }
+
+  if (projects === true) {
+    baseConfig.test.projects = [
+      // default fallback to catch tests directly in /test folder
+      {
+        test: {
+          name: 'default',
+          include: ['{test,tests}/**/*.{test,spec}.ts', '!test/{browser,e2e,nuxt,unit}/**'],
+          environment: 'node',
+        },
+      },
+      // proposed setup for Unit tests
+      {
+        test: {
+          name: 'node',
+          include: ['test/unit/**/*.{test,spec}.ts'],
+          environment: 'node',
+        },
+      },
+      // proposed setup for Nuxt component tests
+      await defineVitestProject({
+        test: {
+          name: 'nuxt',
+          include: ['test/nuxt/**/*.{test,spec}.ts'],
+          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',
+          // create report file for visual regression testing
+          globalSetup: [screenshotReportSetup],
+        },
+      },
+      // 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 mergeConfig(userVitestConfig, defineConfig(baseConfig))
+}

package/config/templates/pnpm-workspace.yaml.template

@@ -1,4 +1,4 @@
-# settings for Nuxt & pnpm
-
-# https://pnpm.io/settings#shamefullyhoist
-shamefullyHoist: true
+# settings for Nuxt & pnpm
+
+# https://pnpm.io/settings#shamefullyhoist
+shamefullyHoist: true

package/config/templates/vitest.config.ts.template

@@ -1,5 +1,5 @@
-import { loadVitestConfig } from 'nuxt-spec/config'
-
-export default loadVitestConfig({
-  // custom config here
-})
+import { loadVitestConfig } from 'nuxt-spec/config'
+
+export default loadVitestConfig({
+  // custom config here
+})

package/config/utils/merge.mjs

@@ -1,43 +1,43 @@
-// 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 in OVERRIDE instead of merging with nuxt-spec defaults
-
-import { createDefu } from 'defu'
-
-// in real Vitest config, "name" is nested inside another "test" object
-const getProjectName = project => project?.name ?? project?.test?.name
-
-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 => getProjectName(o) === getProjectName(defaultProject))
-      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 => getProjectName(d) === getProjectName(override))) {
-        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
-  }
-})
+// 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 in OVERRIDE instead of merging with nuxt-spec defaults
+
+import { createDefu } from 'defu'
+
+// in real Vitest config, "name" is nested inside another "test" object
+const getProjectName = project => project?.name ?? project?.test?.name
+
+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 => getProjectName(o) === getProjectName(defaultProject))
+      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 => getProjectName(d) === getProjectName(override))) {
+        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/config/utils/warnings.mjs

@@ -1,33 +1,33 @@
-const messageFilters = [
-  // 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
-// (applied as side-effect on import)
-
-const _stderrWrite = process.stderr.write.bind(process.stderr)
-process.stderr.write = (chunk, ...args) => {
-  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
-  return _stderrWrite(chunk, ...args)
-}
-
-const _stdoutWrite = process.stdout.write.bind(process.stdout)
-process.stdout.write = (chunk, ...args) => {
-  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
-  return _stdoutWrite(chunk, ...args)
-}
-
-// 2) filter-out unnecessary console logs coming from Vitest
-// (used as Vitest onConsoleLog hook)
-
-export function onConsoleLog(log) {
-  if (messageFilters.some(f => log.includes(f))) return false
-}
+const messageFilters = [
+  // 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
+// (applied as side-effect on import)
+
+const _stderrWrite = process.stderr.write.bind(process.stderr)
+process.stderr.write = (chunk, ...args) => {
+  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
+  return _stderrWrite(chunk, ...args)
+}
+
+const _stdoutWrite = process.stdout.write.bind(process.stdout)
+process.stdout.write = (chunk, ...args) => {
+  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
+  return _stdoutWrite(chunk, ...args)
+}
+
+// 2) filter-out unnecessary console logs coming from Vitest
+// (used as Vitest onConsoleLog hook)
+
+export function onConsoleLog(log) {
+  if (messageFilters.some(f => log.includes(f))) return false
+}

package/nuxt.config.ts

@@ -1,19 +1,19 @@
-export default defineNuxtConfig({
-  modules: [
-    '@nuxt/eslint',
-    '@nuxt/test-utils/module',
-  ],
-
-  // exclude file used for explicit exports (nuxt-spec/components) from Nuxt resolution
-  components: {
-    dirs: [{ path: '~/components', ignore: ['index.ts'] }],
-  },
-
-  compatibilityDate: '2026-06-01',
-
-  eslint: {
-    config: {
-      stylistic: true,
-    },
-  },
-})
+export default defineNuxtConfig({
+  modules: [
+    '@nuxt/eslint',
+    '@nuxt/test-utils/module',
+  ],
+
+  // exclude file used for explicit exports (nuxt-spec/components) from Nuxt resolution
+  components: {
+    dirs: [{ path: '~/components', ignore: ['index.ts'] }],
+  },
+
+  compatibilityDate: '2026-06-01',
+
+  eslint: {
+    config: {
+      stylistic: true,
+    },
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.2.3",
+  "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/eslint": "~1.16.0",
     "@nuxt/test-utils": "4.0.3",
-    "@vitejs/plugin-vue": "6.0.7",
-    "@vitest/browser": "4.1.8",
-    "@vitest/browser-playwright": "4.1.8",
-    "@vitest/ui": "4.1.8",
-    "@vue/test-utils": "2.4.10",
+    "@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.9.0",
-    "nuxt": "4.4.7",
-    "pixelmatch": "7.2.0",
-    "playwright-core": "1.60.0",
-    "typescript": "6.0.3",
-    "vitest": "4.1.8",
+    "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.35",
-    "vue-router": "5.1.0"
+    "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/e2e.ts

@@ -1,30 +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()
-}
+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/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>