nuxt-spec 0.3.4 → 0.4.0-alpha.2

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,44 @@
-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(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
+  }
+  if (typeof paramValue !== 'string') {
+    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(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
+  }
+  if (typeof paramValue !== 'number') {
+    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(`[Nuxt Spec] Passed value '${paramName}' is missing or empty.\n${locationHint()}`)
+    return
+  }
+  if (typeof paramValue !== 'object') {
+    console.warn(`[Nuxt Spec] 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(`[Nuxt Spec] 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/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/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,28 @@
-// 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 `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'
+
+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[]) {
+    // @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>',
+    })
+  }
+}