nuxt-spec 0.3.3 → 0.3.4

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,24 +1,24 @@
-// @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'] : []),
-  ],
-
-  // exclude file used for explicit exports (nuxt-spec/components) from Nuxt resolution
-  components: {
-    dirs: [{ path: '~/components', ignore: ['index.ts'] }],
-  },
-
-  compatibilityDate: '2026-08-08',
-
-  eslint: {
-    config: {
-      stylistic: true,
-    },
-  },
-})
+// @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'] : []),
+  ],
+
+  // exclude file used for explicit exports (nuxt-spec/components) from Nuxt resolution
+  components: {
+    dirs: [{ path: '~/components', ignore: ['index.ts'] }],
+  },
+
+  compatibilityDate: '2026-08-08',
+
+  eslint: {
+    config: {
+      stylistic: true,
+    },
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": {
     "type": "git",
@@ -9,20 +9,6 @@
   "license": "MIT",
   "type": "module",
   "main": "./nuxt.config.ts",
-  "scripts": {
-    "analyze": "nuxt analyze",
-    "eslint": "eslint .",
-    "typecheck": "nuxi typecheck",
-    "build": "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"
   },
@@ -62,16 +48,30 @@
     "@vue/test-utils": "2.5.0",
     "elrh-cosca": "0.3.6",
     "fast-png": "~8.0.0",
-    "happy-dom": "~20.12.0",
+    "h3-next": "npm:h3@~2.0.1-rc.31",
+    "happy-dom": "~20.14.0",
     "nuxt": "4.5.2",
     "pixelmatch": "~7.2.0",
+    "playwright": "~1.62.1",
     "playwright-core": "~1.62.1",
     "typescript": "~6.0.3",
     "vitest": "4.1.11",
     "vitest-browser-vue": "2.1.0",
     "vue": "~3.5.42",
-    "vue-router": "~5.3.0",
+    "vue-router": "~5.3.1",
     "vue-tsc": "~3.3.11"
   },
-  "packageManager": "pnpm@11.24.0"
-}
+  "scripts": {
+    "analyze": "nuxt analyze",
+    "eslint": "eslint .",
+    "typecheck": "nuxi typecheck",
+    "build": "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"
+  }
+}

package/utils/e2e.ts

@@ -1,131 +1,131 @@
-import { createPage, url } from '@nuxt/test-utils/e2e'
-import type { GotoOptions, NuxtPage } from '@nuxt/test-utils'
-import { checkPageParam, checkStringParam } from './helpers/check-params'
-
-/**
- * Extra settings object for `gotoPage()` function.
- * All properties are optional.
- */
-export type GotoPageOptions = {
-  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
-  waitUntil?: GotoOptions['waitUntil']
-}
-
-/**
- * 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>`)
- * @param options - Optional extra settings (see `GotoPageOptions`)
- * @returns Playwright page instance after navigation and `hydration` event
- */
-export async function gotoPage(pageName: string, options?: GotoPageOptions): Promise<NuxtPage> {
-  const { waitUntil } = options ?? {}
-
-  // verify params
-  checkStringParam('gotoPage:pageName', pageName)
-  if (waitUntil) {
-    checkStringParam('gotoPage:options.waitUntil', waitUntil)
-  }
-
-  // construct NuxtPage instance
-  const page = await createPage()
-  const urlPath = pageName.startsWith('/') ? url(pageName) : url(`/${pageName}`)
-  await page.goto(urlPath, { waitUntil: waitUntil ?? 'hydration' })
-
-  return page
-}
-
-/**
- * Extra settings object for `getDataHtml()` function.
- * All properties are optional.
- */
-export type GetDataHtmlOptions = {
-  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
-  waitUntil?: GotoOptions['waitUntil']
-  /** CSS selector identifying the target element (defaults to `<body>` tag) */
-  element?: string
-}
-
-/**
- * Extract inner HTML content from a specified element on a given page.
- * If no element is specified via `options.element`, the entire `<body>` content is returned.
- *
- * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
- * @param options - Optional extra settings (see `GetDataHtmlOptions`)
- * @returns The inner HTML of the matched element
- */
-export async function getDataHtml(page: NuxtPage | string, options?: GetDataHtmlOptions): Promise<string> {
-  const { waitUntil, element } = options ?? {}
-
-  // verify params
-  if (typeof page === 'string') {
-    checkStringParam('getDataHtml:page', page)
-  }
-  if (waitUntil) {
-    checkStringParam('getDataHtml:options.waitUntil', waitUntil)
-  }
-  if (element) {
-    checkStringParam('getDataHtml:options.element', element)
-  }
-
-  // get NuxtPage instance
-  const pageInstance = typeof page === 'string' ? await gotoPage(page, { waitUntil }) : page
-  checkPageParam('getDataHtml:pageInstance', pageInstance)
-
-  // extract target HTML
-  const dataElement = pageInstance.locator(element ?? 'body')
-  return await dataElement.innerHTML()
-}
-
-/**
- * Extra settings object for `getAPIResultHtml()` function.
- * Due to nature of the function, `triggerElement`, `targetUrl`, and `responseElement` are required.
- */
-export type GetAPIResultHtmlOptions = {
-  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
-  waitUntil?: GotoOptions['waitUntil']
-  /** CSS selector for the clickable element that triggers the API request (required) */
-  triggerElement: string
-  /** Substring matched against the response URL to identify the expected API call (required) */
-  targetUrl: string
-  /** CSS selector for the element displaying the API response (required) */
-  responseElement: 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 options - Extra settings (see `GetAPIResultHtmlOptions`)
- * @returns The inner HTML of the response element
- */
-export async function getAPIResultHtml(page: NuxtPage | string, options: GetAPIResultHtmlOptions) {
-  const { waitUntil, triggerElement, targetUrl, responseElement } = options
-
-  // verify params
-  if (typeof page === 'string') {
-    checkStringParam('getAPIResultHtml:page', page)
-  }
-  if (waitUntil) {
-    checkStringParam('getAPIResultHtml:options.waitUntil', waitUntil)
-  }
-  checkStringParam('getAPIResultHtml:triggerElement', triggerElement)
-  checkStringParam('getAPIResultHtml:targetUrl', targetUrl)
-  checkStringParam('getAPIResultHtml:responseElement', responseElement)
-
-  // get NuxtPage instance
-  const pageInstance = typeof page === 'string' ? await gotoPage(page, { waitUntil }) : page
-  checkPageParam('getAPIResultHtml:pageInstance', pageInstance)
-
-  // trigger API call
-  await pageInstance.click(triggerElement)
-  await pageInstance.waitForResponse(response =>
-    response.url().includes(targetUrl) && response.ok(),
-  )
-
-  // extract target HTML
-  const dataElement = pageInstance.locator(responseElement)
-  return await dataElement.innerHTML()
-}
+import { createPage, url } from '@nuxt/test-utils/e2e'
+import type { GotoOptions, NuxtPage } from '@nuxt/test-utils'
+import { checkPageParam, checkStringParam } from './helpers/check-params'
+
+/**
+ * Extra settings object for `gotoPage()` function.
+ * All properties are optional.
+ */
+export type GotoPageOptions = {
+  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
+  waitUntil?: GotoOptions['waitUntil']
+}
+
+/**
+ * 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>`)
+ * @param options - Optional extra settings (see `GotoPageOptions`)
+ * @returns Playwright page instance after navigation and `hydration` event
+ */
+export async function gotoPage(pageName: string, options?: GotoPageOptions): Promise<NuxtPage> {
+  const { waitUntil } = options ?? {}
+
+  // verify params
+  checkStringParam('gotoPage:pageName', pageName)
+  if (waitUntil) {
+    checkStringParam('gotoPage:options.waitUntil', waitUntil)
+  }
+
+  // construct NuxtPage instance
+  const page = await createPage()
+  const urlPath = pageName.startsWith('/') ? url(pageName) : url(`/${pageName}`)
+  await page.goto(urlPath, { waitUntil: waitUntil ?? 'hydration' })
+
+  return page
+}
+
+/**
+ * Extra settings object for `getDataHtml()` function.
+ * All properties are optional.
+ */
+export type GetDataHtmlOptions = {
+  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
+  waitUntil?: GotoOptions['waitUntil']
+  /** CSS selector identifying the target element (defaults to `<body>` tag) */
+  element?: string
+}
+
+/**
+ * Extract inner HTML content from a specified element on a given page.
+ * If no element is specified via `options.element`, the entire `<body>` content is returned.
+ *
+ * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
+ * @param options - Optional extra settings (see `GetDataHtmlOptions`)
+ * @returns The inner HTML of the matched element
+ */
+export async function getDataHtml(page: NuxtPage | string, options?: GetDataHtmlOptions): Promise<string> {
+  const { waitUntil, element } = options ?? {}
+
+  // verify params
+  if (typeof page === 'string') {
+    checkStringParam('getDataHtml:page', page)
+  }
+  if (waitUntil) {
+    checkStringParam('getDataHtml:options.waitUntil', waitUntil)
+  }
+  if (element) {
+    checkStringParam('getDataHtml:options.element', element)
+  }
+
+  // get NuxtPage instance
+  const pageInstance = typeof page === 'string' ? await gotoPage(page, { waitUntil }) : page
+  checkPageParam('getDataHtml:pageInstance', pageInstance)
+
+  // extract target HTML
+  const dataElement = pageInstance.locator(element ?? 'body')
+  return await dataElement.innerHTML()
+}
+
+/**
+ * Extra settings object for `getAPIResultHtml()` function.
+ * Due to nature of the function, `triggerElement`, `targetUrl`, and `responseElement` are required.
+ */
+export type GetAPIResultHtmlOptions = {
+  /** Event to be awaited before NuxtPage instance is returned (defaults to `'hydration'`) */
+  waitUntil?: GotoOptions['waitUntil']
+  /** CSS selector for the clickable element that triggers the API request (required) */
+  triggerElement: string
+  /** Substring matched against the response URL to identify the expected API call (required) */
+  targetUrl: string
+  /** CSS selector for the element displaying the API response (required) */
+  responseElement: 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 options - Extra settings (see `GetAPIResultHtmlOptions`)
+ * @returns The inner HTML of the response element
+ */
+export async function getAPIResultHtml(page: NuxtPage | string, options: GetAPIResultHtmlOptions) {
+  const { waitUntil, triggerElement, targetUrl, responseElement } = options
+
+  // verify params
+  if (typeof page === 'string') {
+    checkStringParam('getAPIResultHtml:page', page)
+  }
+  if (waitUntil) {
+    checkStringParam('getAPIResultHtml:options.waitUntil', waitUntil)
+  }
+  checkStringParam('getAPIResultHtml:triggerElement', triggerElement)
+  checkStringParam('getAPIResultHtml:targetUrl', targetUrl)
+  checkStringParam('getAPIResultHtml:responseElement', responseElement)
+
+  // get NuxtPage instance
+  const pageInstance = typeof page === 'string' ? await gotoPage(page, { waitUntil }) : page
+  checkPageParam('getAPIResultHtml:pageInstance', pageInstance)
+
+  // trigger API call
+  await pageInstance.click(triggerElement)
+  await pageInstance.waitForResponse(response =>
+    response.url().includes(targetUrl) && response.ok(),
+  )
+
+  // extract target HTML
+  const dataElement = pageInstance.locator(responseElement)
+  return await dataElement.innerHTML()
+}

package/utils/helpers/check-params.ts

@@ -1,41 +1,41 @@
-import type { NuxtPage } from '@nuxt/test-utils'
-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()}`)
-  }
-  if (typeof paramValue !== 'string') {
-    console.warn(`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()}`)
-  }
-  if (typeof paramValue !== 'number') {
-    console.warn(`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()}`)
-  }
-  if (typeof paramValue !== 'object') {
-    console.warn(`Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
-  } else {
-    const pageInstance = paramValue as unknown as Record<string, unknown>
-    if (
-      typeof pageInstance.goto !== 'function'
-      || typeof pageInstance.locator !== 'function'
-      || typeof pageInstance.waitForResponse !== 'function'
-    ) {
-      console.warn(`Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
-    }
-  }
-}
+import type { NuxtPage } from '@nuxt/test-utils'
+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()}`)
+  }
+  if (typeof paramValue !== 'string') {
+    console.warn(`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()}`)
+  }
+  if (typeof paramValue !== 'number') {
+    console.warn(`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()}`)
+  }
+  if (typeof paramValue !== 'object') {
+    console.warn(`Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
+  } else {
+    const pageInstance = paramValue as unknown as Record<string, unknown>
+    if (
+      typeof pageInstance.goto !== 'function'
+      || typeof pageInstance.locator !== 'function'
+      || typeof pageInstance.waitForResponse !== 'function'
+    ) {
+      console.warn(`Passed value '${paramName}' is not a NuxtPage.\n${locationHint()}`)
+    }
+  }
+}

package/utils/helpers/location-hint.ts

@@ -1,30 +1,30 @@
-import { createRequire } from 'node:module'
-import { dirname } from 'node:path'
-
-// shows "(at path-to-file:line:column)" hint to locate cause from stack trace
-// this syntax allow tools like VS Code to create clickable link directly to the source
-export function locationHint(): string {
-  return `  (at ${getCallSite()})`
-}
-
-// path to nuxt-spec/utils directory computed on runtime
-const pkgUtilsDir = normalizePath(dirname(createRequire(import.meta.url).resolve('nuxt-spec/utils')))
-
-// handle possible Win backslashes
-function normalizePath(path: string): string {
-  return path.replace(/^file:\/\//, '').replace(/\\/g, '/')
-}
-
-// locate first stack frame outside of nuxt-spec utils
-// which will the place where the utility function is being called from
-function getCallSite(): string | undefined {
-  const stack = new Error().stack?.split('\n').slice(1) ?? []
-  for (const raw of stack) {
-    const match = raw.match(/\(?((?:file:\/\/)?[^()\s]+:\d+:\d+)\)?\s*$/)
-    if (!match?.[1]) continue
-    const location = normalizePath(match[1])
-    if (location.includes(pkgUtilsDir)) continue
-    return location
-  }
-  return undefined
-}
+import { createRequire } from 'node:module'
+import { dirname } from 'node:path'
+
+// shows "(at path-to-file:line:column)" hint to locate cause from stack trace
+// this syntax allow tools like VS Code to create clickable link directly to the source
+export function locationHint(): string {
+  return `  (at ${getCallSite()})`
+}
+
+// path to nuxt-spec/utils directory computed on runtime
+const pkgUtilsDir = normalizePath(dirname(createRequire(import.meta.url).resolve('nuxt-spec/utils')))
+
+// handle possible Win backslashes
+function normalizePath(path: string): string {
+  return path.replace(/^file:\/\//, '').replace(/\\/g, '/')
+}
+
+// locate first stack frame outside of nuxt-spec utils
+// which will the place where the utility function is being called from
+function getCallSite(): string | undefined {
+  const stack = new Error().stack?.split('\n').slice(1) ?? []
+  for (const raw of stack) {
+    const match = raw.match(/\(?((?:file:\/\/)?[^()\s]+:\d+:\d+)\)?\s*$/)
+    if (!match?.[1]) continue
+    const location = normalizePath(match[1])
+    if (location.includes(pkgUtilsDir)) continue
+    return location
+  }
+  return undefined
+}

package/utils/index.ts

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

package/utils/playwright.ts

@@ -1,20 +1,20 @@
-// Vitest setup file for the `e2e` project
-// allows connecting to an external Playwright instance,
-// if NUXT_SPEC_EXTERNAL_PLAYWRIGHT is set
-
-import { chromium, firefox, webkit } from 'playwright-core'
-import type { Browser, BrowserType } from 'playwright-core'
-
-const externalPlaywright = process.env.NUXT_SPEC_EXTERNAL_PLAYWRIGHT
-
-if (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, {
-      // this allows reaching caller's localhost from within the external Playwright
-      exposeNetwork: '<loopback>',
-    })
-  }
-}
+// Vitest setup file for the `e2e` project
+// allows connecting to an external Playwright instance,
+// if NUXT_SPEC_EXTERNAL_PLAYWRIGHT is set
+
+import { chromium, firefox, webkit } from 'playwright-core'
+import type { Browser, BrowserType } from 'playwright-core'
+
+const externalPlaywright = process.env.NUXT_SPEC_EXTERNAL_PLAYWRIGHT
+
+if (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, {
+      // this allows reaching caller's localhost from within the external Playwright
+      exposeNetwork: '<loopback>',
+    })
+  }
+}