nuxt-spec 0.2.4 → 0.3.0-alpha.2

package/utils/e2e.ts

@@ -1,30 +1,131 @@
-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 { 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

@@ -0,0 +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()}`)
+    }
+  }
+}

package/utils/helpers/location-hint.ts

@@ -0,0 +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
+}

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/screenshot/report-entry.html

@@ -1,8 +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>
+<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/screenshot/report-head.html

@@ -1,24 +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 -->
+<!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/screenshot/report-tail.html

@@ -1,4 +1,4 @@
-<!-- END failed screenshot entries -->
- <div>Generated by <a href="https://github.com/nuxt/nuxt-spec">Nuxt Spec</a> @ {{TIMESTAMP}}</div>
-</body>
-</html>
+<!-- END failed screenshot entries -->
+ <div>Generated by <a href="https://github.com/nuxt/nuxt-spec">Nuxt Spec</a> @ {{TIMESTAMP}}</div>
+</body>
+</html>