nuxt-spec 0.3.3 → 0.4.0-alpha.1

package/config/utils/reporter.mjs

@@ -0,0 +1,409 @@
+// HTML test report for Nuxt Spec
+// - `NuxtSpecHtmlReporter` is a Vitest reporter that renders a self-contained HTML file
+//   into `<root>/test/__reports__/report-YYYYMMDDHHMMSS.html` after each test run
+// - `nuxtSpecReportPlugin` is a Vite plugin that appends the reporter to whatever reporters
+//   are in effect (CLI `--reporter`, user config or Vitest defaults)
+// - `open` option (always|failed|never) controls opening the report in browser
+
+import { exec } from 'node:child_process'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import { relative, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+/** Artifact type recorded by `compareScreenshot` on mismatch */
+export const SCREENSHOT_ARTIFACT_TYPE = 'nuxt-spec:screenshot'
+
+/** Relative path (from Vitest root) where report files are stored */
+export const REPORT_DIR = 'test/__reports__'
+
+const OPEN_MODES = ['always', 'failed', 'never']
+
+// marker used to identify the reporter instance even if this module is loaded more than once
+const REPORTER_MARK = Symbol.for('nuxt-spec:html-reporter')
+
+const templatesDir = fileURLToPath(new URL('../report/', import.meta.url))
+const loadTemplate = name => readFileSync(resolve(templatesDir, name), 'utf-8')
+
+/**
+ * Vite plugin that registers `NuxtSpecHtmlReporter`.
+ * The `configureVitest` hook runs after Vitest merged CLI and config reporters,
+ * but before reporters are instantiated, so the HTML reporter is always appended.
+ * @param {ReporterOptions} [options] - reporter options
+ */
+export function nuxtSpecReportPlugin(options = {}) {
+  return {
+    name: 'nuxt-spec:html-report',
+    configureVitest({ vitest }) {
+      addReporter(vitest.config, options)
+    },
+  }
+}
+
+/**
+ * Append the Nuxt Spec HTML reporter into resolved Vitest config.
+ * The hook is called once per project, so duplicates must be avoided.
+ * @param {{ reporters?: unknown[] }} config - resolved Vitest config
+ * @param {ReporterOptions} [options] - reporter options
+ */
+export function addReporter(config, options = {}) {
+  config.reporters ??= []
+  if (config.reporters.some(r => r?.[REPORTER_MARK])) return
+  config.reporters.push(new NuxtSpecHtmlReporter(options))
+}
+
+/**
+ * @typedef {{ open?: string }} ReporterOptions
+ */
+
+export class NuxtSpecHtmlReporter {
+  [REPORTER_MARK] = true
+
+  /** @param {ReporterOptions} [options] */
+  constructor({ open } = {}) {
+    this.open = open
+  }
+
+  onInit(vitest) {
+    this.vitest = vitest
+  }
+
+  onTestRunStart() {
+    this.startedAt = new Date()
+  }
+
+  onTestRunEnd(testModules, unhandledErrors, reason) {
+    const startedAt = this.startedAt ?? new Date()
+    const root = this.vitest?.config?.root ?? process.cwd()
+    const watch = !!this.vitest?.config?.watch
+    const log = (msg) => {
+      if (this.vitest?.logger) this.vitest.logger.log(msg)
+      else console.log(msg)
+    }
+
+    const data = collectReportData(testModules, unhandledErrors, reason, root)
+    const html = renderReport(data, reportTimestamp(startedAt, true), new Date().toISOString())
+
+    const reportDir = resolve(root, REPORT_DIR)
+    const reportPath = resolve(reportDir, `report-${reportTimestamp(startedAt)}.html`)
+    try {
+      mkdirSync(reportDir, { recursive: true })
+      writeFileSync(reportPath, html)
+    } catch (error) {
+      log(`\n[Nuxt Spec] Failed to write HTML report: ${error?.message ?? error}`)
+      return
+    }
+
+    log(`\n[Nuxt Spec] Test report available at:\n${pathToFileURL(reportPath).href}`)
+
+    const shouldOpen = shouldOpenReport({
+      mode: this.open,
+      hasFailure: data.hasFailure,
+      ci: !!process.env.CI,
+      watch,
+    })
+    if (shouldOpen) {
+      log('[Nuxt Spec] Opening report in default browser...')
+      openInBrowser(reportPath, () => log('[Nuxt Spec] Failed to automatically open report'))
+    }
+  }
+}
+
+/**
+ * Decide whether the report should be opened in the default browser.
+ * Never opens in CI or watch mode. Invalid `mode` falls back to `failed`.
+ * @param {{ mode?: string, hasFailure: boolean, ci: boolean, watch: boolean }} options
+ */
+export function shouldOpenReport({ mode, hasFailure, ci, watch }) {
+  if (ci || watch) return false
+  const normalized = mode?.trim().toLowerCase() || 'failed'
+  const effective = OPEN_MODES.includes(normalized) ? normalized : 'failed'
+  if (effective === 'always') return true
+  if (effective === 'never') return false
+  return hasFailure
+}
+
+/**
+ * @typedef {{ message: string, diff?: string, stack?: string }} ReportError
+ * @typedef {{ fileName: string, message: string, baselineUri?: string, actualUri?: string }} ReportScreenshot
+ * @typedef {{ project: string, file: string, name: string, errors: ReportError[], screenshots: ReportScreenshot[] }} ReportFailure
+ * @typedef {{ project: string, file: string, suite: string, errors: ReportError[] }} ReportModuleError
+ * @typedef {{
+ *   total: number,
+ *   passed: number,
+ *   failed: number,
+ *   skipped: number,
+ *   reason: 'passed' | 'failed' | 'interrupted',
+ *   failures: ReportFailure[],
+ *   moduleErrors: ReportModuleError[],
+ *   unhandledErrors: ReportError[],
+ *   hasFailure: boolean,
+ * }} ReportData
+ */
+
+/**
+ * Transform Vitest reported entities into plain report data.
+ * @param {ReadonlyArray<any>} testModules - `TestModule` instances from `onTestRunEnd`
+ * @param {ReadonlyArray<any>} unhandledErrors - serialized unhandled errors
+ * @param {'passed' | 'failed' | 'interrupted'} reason - run end reason
+ * @param {string} root - project root used to compute relative paths
+ * @returns {ReportData}
+ */
+export function collectReportData(testModules, unhandledErrors, reason, root) {
+  /** @type {ReportData} */
+  const data = {
+    total: 0,
+    passed: 0,
+    failed: 0,
+    skipped: 0,
+    reason,
+    failures: [],
+    moduleErrors: [],
+    unhandledErrors: (unhandledErrors ?? []).map(toErrorData),
+    hasFailure: false,
+  }
+
+  for (const testModule of testModules ?? []) {
+    const project = testModule.project?.name || ''
+    const file = toRelative(root, testModule.moduleId)
+
+    // errors outside of tests - module collection errors or failed `beforeAll`/`afterAll` hooks
+    const moduleErrors = testModule.errors?.() ?? []
+    if (moduleErrors.length > 0) {
+      data.moduleErrors.push({ project, file, suite: '', errors: moduleErrors.map(toErrorData) })
+    }
+    for (const testSuite of testModule.children?.allSuites() ?? []) {
+      const suiteErrors = testSuite.errors?.() ?? []
+      if (suiteErrors.length > 0) {
+        data.moduleErrors.push({ project, file, suite: testSuite.fullName ?? testSuite.name, errors: suiteErrors.map(toErrorData) })
+      }
+    }
+
+    for (const testCase of testModule.children?.allTests() ?? []) {
+      const result = testCase.result()
+      if (result.state === 'skipped') {
+        data.skipped++
+        continue
+      }
+      data.total++
+      if (result.state === 'passed') {
+        data.passed++
+      } else if (result.state === 'failed') {
+        data.failed++
+        data.failures.push({
+          project,
+          file,
+          name: testCase.fullName ?? testCase.name,
+          errors: (result.errors ?? []).map(toErrorData),
+          screenshots: (testCase.artifacts?.() ?? [])
+            .filter(a => a?.type === SCREENSHOT_ARTIFACT_TYPE)
+            .map(toScreenshotData),
+        })
+      }
+    }
+  }
+
+  data.hasFailure = data.failed > 0
+    || data.moduleErrors.length > 0
+    || data.unhandledErrors.length > 0
+    || reason !== 'passed'
+
+  return data
+}
+
+/**
+ * Render report data (see `collectReportData`) into a self-contained HTML document.
+ * @param {ReportData} data
+ * @param {string} titleTimestamp - timestamp displayed in the report title
+ * @param {string} footerTimestamp - timestamp displayed in the report footer
+ */
+export function renderReport(data, titleTimestamp, footerTimestamp) {
+  const entries = []
+
+  for (const failure of data.failures) {
+    entries.push(renderEntry({
+      title: failure.name,
+      location: formatLocation(failure.project, failure.file),
+      errors: failure.errors,
+      screenshots: failure.screenshots,
+    }))
+  }
+
+  for (const moduleError of data.moduleErrors) {
+    entries.push(renderEntry({
+      title: moduleError.suite ? `Error in suite: ${moduleError.suite}` : 'Error in test module',
+      location: formatLocation(moduleError.project, moduleError.file),
+      errors: moduleError.errors,
+    }))
+  }
+
+  for (const error of data.unhandledErrors) {
+    entries.push(renderEntry({
+      title: 'Unhandled error',
+      location: 'Error was thrown outside of a test',
+      errors: [error],
+    }))
+  }
+
+  const head = fillTemplate(loadTemplate('report-head.html'), {
+    TIMESTAMP: escapeHtml(titleTimestamp),
+    STATUS: data.hasFailure ? 'failed' : 'passed',
+    SUMMARY: escapeHtml(formatSummary(data)),
+  })
+  const tail = fillTemplate(loadTemplate('report-tail.html'), {
+    TIMESTAMP: escapeHtml(footerTimestamp),
+  })
+
+  return head + entries.join('') + tail
+}
+
+/**
+ * Build the one-line summary, e.g. `5/5 tests passed` or `3/5 tests passed, 2 failed`.
+ * @param {ReportData} data
+ */
+export function formatSummary(data) {
+  const parts = [`${data.passed}/${data.total} tests passed`]
+  if (data.failed > 0) parts.push(`${data.failed} failed`)
+  if (data.skipped > 0) parts.push(`${data.skipped} skipped`)
+  if (data.moduleErrors.length > 0) parts.push(`${data.moduleErrors.length} module/suite error(s)`)
+  if (data.unhandledErrors.length > 0) parts.push(`${data.unhandledErrors.length} unhandled error(s)`)
+  let summary = parts.join(', ')
+  if (data.reason === 'interrupted') summary += ' (test run was interrupted)'
+  else if (data.hasFailure && data.failed === 0 && data.moduleErrors.length === 0 && data.unhandledErrors.length === 0) {
+    summary += ' (test run failed)'
+  }
+  return summary
+}
+
+function renderEntry({ title, location, errors, screenshots = [] }) {
+  return fillTemplate(loadTemplate('report-entry.html'), {
+    TITLE: escapeHtml(title),
+    LOCATION: escapeHtml(location),
+    ERRORS: errors.map(renderError).join('\n'),
+    SCREENSHOTS: screenshots.map(renderScreenshot).join('\n'),
+  })
+}
+
+function renderError(error) {
+  let html = `<pre class="message">${escapeHtml(error.message)}</pre>`
+  if (error.diff) {
+    html += `<details open><summary>Diff</summary><pre class="diff">${escapeHtml(error.diff)}</pre></details>`
+  }
+  if (error.stack) {
+    html += `<details><summary>Stack trace</summary><pre class="stack">${escapeHtml(error.stack)}</pre></details>`
+  }
+  return html
+}
+
+function renderScreenshot(screenshot) {
+  // attachments may be missing (e.g. stripped by Vitest), show at least the message
+  if (!screenshot.baselineUri || !screenshot.actualUri) {
+    return `<div class="screenshot"><h3>${escapeHtml(screenshot.fileName)}</h3><p class="message">${escapeHtml(screenshot.message)}</p></div>`
+  }
+  return fillTemplate(loadTemplate('report-screenshot.html'), {
+    FILE_NAME: escapeHtml(screenshot.fileName),
+    MESSAGE: escapeHtml(screenshot.message),
+    BASELINE_URI: screenshot.baselineUri,
+    ACTUAL_URI: screenshot.actualUri,
+  })
+}
+
+function toErrorData(error) {
+  const name = error?.name && error.name !== 'Error' ? `${error.name}: ` : ''
+  return {
+    message: stripAnsi(`${name}${error?.message ?? String(error)}`),
+    diff: error?.diff ? stripAnsi(error.diff) : undefined,
+    stack: error?.stack ? stripAnsi(error.stack) : undefined,
+  }
+}
+
+function toScreenshotData(artifact) {
+  const attachments = artifact.attachments ?? []
+  const findUri = (name) => {
+    const attachment = attachments.find(a => a?.name === name)
+    if (!attachment?.body || typeof attachment.body !== 'string') return undefined
+    if (attachment.bodyEncoding === 'utf-8') return undefined
+    // only accept valid base64 payload and an image MIME type to keep the `src` attribute safe
+    if (!BASE64_REGEX.test(attachment.body)) return undefined
+    const contentType = IMAGE_MIME_REGEX.test(attachment.contentType ?? '') ? attachment.contentType : 'image/png'
+    return `data:${contentType};base64,${attachment.body}`
+  }
+  return {
+    fileName: artifact.fileName ?? '',
+    message: artifact.message ?? '',
+    baselineUri: findUri('baseline'),
+    actualUri: findUri('actual'),
+  }
+}
+
+function formatLocation(project, file) {
+  return project ? `[${project}] ${file}` : file
+}
+
+function toRelative(root, path) {
+  if (!path) return ''
+  const rel = relative(root, path)
+  return rel && !rel.startsWith('..') ? rel.replaceAll('\\', '/') : path
+}
+
+function openInBrowser(path, onError) {
+  const openCmd
+    = platform() === 'darwin'
+      ? `open "${path}"`
+      : platform() === 'win32'
+        ? `start "" "${path}"`
+        : `xdg-open "${path}"`
+  exec(openCmd, (err) => {
+    if (err) onError()
+  })
+}
+
+// replace `{{KEY}}` placeholders
+// function replacer avoids special `$` patterns of String.replace
+function fillTemplate(template, values) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => key in values ? values[key] : match)
+}
+
+// timestamp string
+// separators=false produces YYYYMMDDHHMMSS for report file name
+// separators=true produces YYYY-MM-DD HH:MM:SS for report title
+export function reportTimestamp(date, separators = false) {
+  const pad2 = n => 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('')
+}
+
+const BASE64_REGEX = /^[A-Za-z0-9+/]+={0,2}$/
+const IMAGE_MIME_REGEX = /^image\/[a-z0-9.+-]+$/i
+
+// eslint-disable-next-line no-control-regex
+const ANSI_REGEX = /\u001B\[[0-9;?]*[ -/]*[@-~]/g
+
+function stripAnsi(value) {
+  return String(value).replace(ANSI_REGEX, '')
+}
+
+// helper to escape a string for safe interpolation into the HTML report
+function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, char => ({
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    '\'': '&#39;',
+  }[char] ?? char))
+}

package/config/utils/warnings.mjs

@@ -4,12 +4,17 @@ const messageFilters = [
   '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(',')
-    : []),
 ]
 
+// merge user-defined filters (`spec.messageFilters` / NUXT_SPEC_MESSAGE_FILTERS) with defaults
+export function addMessageFilters(filters) {
+  for (const filter of filters) {
+    if (filter && !messageFilters.includes(filter)) {
+      messageFilters.push(filter)
+    }
+  }
+}
+
 // 1) filter-out unnecessary stderr/stdout logs coming from Vitest
 // (applied as side-effect on import)
 

package/modules/spec-options.ts

@@ -0,0 +1,23 @@
+import { defineNuxtModule } from 'nuxt/kit'
+import type { ModuleDependencies, NuxtModule } from 'nuxt/schema'
+import { resolveSpecOptions } from '../config/utils/options.mjs'
+import type { NuxtSpecOptions } from '../config/utils/options.mjs'
+
+// registers typed `spec` key for nuxt.config.ts and applies its Nuxt-related options
+// options related to Vitest are resolved in `loadVitestConfig` (config/index.mjs)
+// (explicit types break circular reference with module types generated by Nuxt)
+const specOptionsModule: NuxtModule<NuxtSpecOptions> = defineNuxtModule<NuxtSpecOptions>({
+  meta: {
+    name: 'nuxt-spec',
+    configKey: 'spec',
+    // used as `@see` link in generated types (fallback would be a broken npm URL)
+    docs: 'https://nuxt-spec.netlify.app/2-1-configuration.html#nuxt-spec-options',
+  },
+  moduleDependencies: (nuxt): ModuleDependencies => {
+    // `spec` is typed only after Nuxt generates module types
+    const { spec } = nuxt.options as unknown as { spec?: NuxtSpecOptions | false }
+    return resolveSpecOptions(spec).hints ? { '@nuxt/hints': {} } : {}
+  },
+})
+
+export default specOptionsModule

package/nuxt.config.ts

@@ -1,12 +1,8 @@
-// @nuxt/hints module is included by default
-// set NUXT_SPEC_HINTS_ENABLED=false to exclude it
-const hintsEnabled = process.env.NUXT_SPEC_HINTS_ENABLED !== 'false'
-
 export default defineNuxtConfig({
   modules: [
     '@nuxt/eslint',
     '@nuxt/test-utils/module',
-    ...(hintsEnabled ? ['@nuxt/hints'] : []),
+    // @nuxt/hints module is handled in `modules/spec-options.ts`
   ],
 
   // exclude file used for explicit exports (nuxt-spec/components) from Nuxt resolution
@@ -14,7 +10,7 @@ export default defineNuxtConfig({
     dirs: [{ path: '~/components', ignore: ['index.ts'] }],
   },
 
-  compatibilityDate: '2026-08-08',
+  compatibilityDate: '2026-10-07',
 
   eslint: {
     config: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.3.3",
+  "version": "0.4.0-alpha.1",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": {
     "type": "git",
@@ -16,7 +16,7 @@
     "build": "nuxt build",
     "dev": "nuxt dev",
     "generate": "nuxt generate",
-    "prepublishOnly": "node bin/prepublish-check.js",
+    "prepublishOnly": "node bin/_internal/prepublish-check.js",
     "preview": "nuxt preview",
     "start": "nuxt start",
     "test": "vitest run",
@@ -47,6 +47,7 @@
     "app",
     "bin",
     "config",
+    "modules",
     "public",
     "utils",
     "nuxt.config.ts"
@@ -54,24 +55,25 @@
   "dependencies": {
     "@nuxt/eslint": "~1.17.0",
     "@nuxt/hints": "1.1.4",
-    "@nuxt/test-utils": "4.2.0",
-    "@vitejs/plugin-vue": "~6.0.8",
-    "@vitest/browser": "4.1.11",
-    "@vitest/browser-playwright": "4.1.11",
-    "@vitest/ui": "4.1.11",
-    "@vue/test-utils": "2.5.0",
-    "elrh-cosca": "0.3.6",
+    "@nuxt/test-utils": "4.3.3",
+    "@vitejs/plugin-vue": "~6.0.9",
+    "@vitest/browser": "5.0.3",
+    "@vitest/browser-playwright": "5.0.3",
+    "@vitest/ui": "5.0.3",
+    "@vue/test-utils": "2.5.1",
+    "elrh-cosca": "0.4.1",
     "fast-png": "~8.0.0",
-    "happy-dom": "~20.12.0",
-    "nuxt": "4.5.2",
+    "happy-dom": "~20.14.5",
+    "nuxt": "4.6.0",
     "pixelmatch": "~7.2.0",
-    "playwright-core": "~1.62.1",
+    "playwright": "~1.63.0",
+    "playwright-core": "~1.63.0",
     "typescript": "~6.0.3",
-    "vitest": "4.1.11",
-    "vitest-browser-vue": "2.1.0",
-    "vue": "~3.5.42",
-    "vue-router": "~5.3.0",
-    "vue-tsc": "~3.3.11"
+    "vitest": "5.0.3",
+    "vitest-browser-vue": "3.1.0",
+    "vue": "~3.5.43",
+    "vue-router": "~5.3.1",
+    "vue-tsc": "~3.3.12"
   },
-  "packageManager": "pnpm@11.24.0"
+  "packageManager": "pnpm@12.9.1"
 }

package/utils/helpers/check-params.ts

@@ -4,30 +4,33 @@ import { locationHint } from './location-hint'
 // given string param must be an actual non-empty string
 export function checkStringParam(paramName: string, paramValue?: string) {
   if (!paramValue) {
-    console.warn(`Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
   }
   if (typeof paramValue !== 'string') {
-    console.warn(`Passed value '${paramName}' is not a string.\n${locationHint()}`)
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a string.\n${locationHint()}`)
   }
 }
 
 // given string param must be an actual number
 export function checkNumberParam(paramName: string, paramValue?: number) {
   if (paramValue === undefined || paramValue === null) {
-    console.warn(`Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
   }
   if (typeof paramValue !== 'number') {
-    console.warn(`Passed value '${paramName}' is not a number.\n${locationHint()}`)
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a number.\n${locationHint()}`)
   }
 }
 
 // given NuxtPage param must be an actual non-nullish NuxtPage instance
 export function checkPageParam(paramName: string, paramValue?: NuxtPage) {
   if (!paramValue) {
-    console.warn(`Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
   }
   if (typeof paramValue !== 'object') {
-    console.warn(`Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
+    console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
   } else {
     const pageInstance = paramValue as unknown as Record<string, unknown>
     if (
@@ -35,7 +38,7 @@ export function checkPageParam(paramName: string, paramValue?: NuxtPage) {
       || typeof pageInstance.locator !== 'function'
       || typeof pageInstance.waitForResponse !== 'function'
     ) {
-      console.warn(`Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
+      console.warn(`[Nuxt Spec] Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
     }
   }
 }

package/utils/helpers/screenshot-utils.ts

@@ -0,0 +1,27 @@
+import { resolve, sep } from 'node:path'
+import type { DecodedPng } from 'fast-png'
+
+// 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(`[Nuxt Spec] 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
+}

package/utils/playwright.ts

@@ -1,15 +1,23 @@
 // Vitest setup file for the `e2e` project
 // allows connecting to an external Playwright instance,
-// if NUXT_SPEC_EXTERNAL_PLAYWRIGHT is set
+// if `spec.externalPlaywright` or NUXT_SPEC_EXTERNAL_PLAYWRIGHT is set
 
+import { inject } from 'vitest'
 import { chromium, firefox, webkit } from 'playwright-core'
 import type { Browser, BrowserType } from 'playwright-core'
 
-const externalPlaywright = process.env.NUXT_SPEC_EXTERNAL_PLAYWRIGHT
+declare module 'vitest' {
+  interface ProvidedContext {
+    nuxtSpecExternalPlaywright?: string
+  }
+}
+
+// resolved and provided by `loadVitestConfig` (config/index.mjs)
+const externalPlaywright = inject('nuxtSpecExternalPlaywright')
 
 if (externalPlaywright) {
+  console.log(`[Nuxt Spec] Using external Playwright instance for e2e tests at: ${externalPlaywright}`)
   for (const browserType of [chromium, firefox, webkit] as BrowserType[]) {
-    console.log(`[Nuxt Spec - e2e] Using external Playwright instance at: ${externalPlaywright}`)
     // @nuxt/test-utils always calls `playwright[type].launch()` with no way to opt into
     // `connect()`, so the launch method is swapped for a connect against the WS endpoint
     browserType.launch = (): Promise<Browser> => browserType.connect(externalPlaywright, {