nuxt-spec 0.3.4 → 0.4.0-alpha.1

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/options.d.mts

@@ -0,0 +1,59 @@
+export type HtmlReportOpenMode = 'always' | 'failed' | 'never'
+
+/**
+ * Nuxt Spec options set via `spec` key in nuxt.config.ts.
+ * Each option can also be set via respective NUXT_SPEC_* env variable,
+ * which takes precedence over the value from nuxt.config.ts.
+ */
+export interface NuxtSpecOptions {
+  /**
+   * Include `@nuxt/hints` module.
+   * Env: `NUXT_SPEC_HINTS_ENABLED`
+   * @default true
+   */
+  hints?: boolean
+  /**
+   * WebSocket endpoint of an external Playwright server used by `e2e` and `browser` projects.
+   * Env: `NUXT_SPEC_EXTERNAL_PLAYWRIGHT`
+   */
+  externalPlaywright?: string
+  /** HTML test report settings */
+  htmlReport?: {
+    /**
+     * Generate HTML report after each test run.
+     * Env: `NUXT_SPEC_HTML_REPORT`
+     * @default true
+     */
+    enabled?: boolean
+    /**
+     * When to open the report in the default browser.
+     * Env: `NUXT_SPEC_HTML_REPORT_OPEN`
+     * @default 'failed'
+     */
+    open?: HtmlReportOpenMode
+  }
+  /**
+   * Plain text patterns of log messages that should be omitted.
+   * Env: `NUXT_SPEC_MESSAGE_FILTERS` (comma-separated, added to values from nuxt.config.ts)
+   */
+  messageFilters?: string[]
+}
+
+export interface ResolvedNuxtSpecOptions {
+  hints: boolean
+  externalPlaywright: string | undefined
+  htmlReport: {
+    enabled: boolean
+    open: HtmlReportOpenMode
+  }
+  messageFilters: string[]
+}
+
+export declare const NUXT_SPEC_DEFAULTS: ResolvedNuxtSpecOptions
+
+export declare function resolveSpecOptions(
+  fromConfig?: NuxtSpecOptions | false | null,
+  env?: Record<string, string | undefined>,
+): ResolvedNuxtSpecOptions
+
+export declare function loadSpecOptions(cwd?: string): Promise<ResolvedNuxtSpecOptions>

package/config/utils/options.mjs

@@ -0,0 +1,116 @@
+// Nuxt Spec options resolution
+// - values can be set via `spec` key in nuxt.config.ts or via NUXT_SPEC_* env variables
+// - precedence: env variables > nuxt.config.ts > defaults
+
+import { loadNuxtConfig } from 'nuxt/kit'
+
+export const NUXT_SPEC_DEFAULTS = {
+  hints: true,
+  externalPlaywright: undefined,
+  htmlReport: {
+    enabled: true,
+    open: 'failed',
+  },
+  messageFilters: [],
+}
+
+const HTML_REPORT_OPEN_MODES = ['always', 'failed', 'never']
+
+// raw `spec` values per cwd - nuxt.config.ts is only loaded once
+const specCache = new Map()
+
+// options are resolved by both the Nuxt module and the Vitest config in the same process
+const reportedWarnings = new Set()
+
+/**
+ * Resolve final Nuxt Spec options.
+ * @param {import('./options.d.mts').NuxtSpecOptions | false | null} [fromConfig] - `spec` key from nuxt.config.ts
+ * @param {Record<string, string | undefined>} [env] - env variables
+ * @returns {import('./options.d.mts').ResolvedNuxtSpecOptions}
+ */
+export function resolveSpecOptions(fromConfig, env = process.env) {
+  const config = isObject(fromConfig) ? fromConfig : {}
+  const htmlReport = checkType('htmlReport', config.htmlReport, 'object') ?? {}
+  return {
+    hints: toBoolean(env.NUXT_SPEC_HINTS_ENABLED)
+      ?? checkType('hints', config.hints, 'boolean')
+      ?? NUXT_SPEC_DEFAULTS.hints,
+    externalPlaywright: env.NUXT_SPEC_EXTERNAL_PLAYWRIGHT
+      || checkType('externalPlaywright', config.externalPlaywright, 'string')
+      || NUXT_SPEC_DEFAULTS.externalPlaywright,
+    htmlReport: {
+      enabled: toBoolean(env.NUXT_SPEC_HTML_REPORT)
+        ?? checkType('htmlReport.enabled', htmlReport.enabled, 'boolean')
+        ?? NUXT_SPEC_DEFAULTS.htmlReport.enabled,
+      open: env.NUXT_SPEC_HTML_REPORT_OPEN
+        ? toOpenMode('NUXT_SPEC_HTML_REPORT_OPEN', env.NUXT_SPEC_HTML_REPORT_OPEN)
+        : toOpenMode('htmlReport.open', htmlReport.open),
+    },
+    messageFilters: [
+      ...(checkType('messageFilters', config.messageFilters, 'array') ?? []),
+      ...(env.NUXT_SPEC_MESSAGE_FILTERS?.split(',') ?? []),
+    ]
+      .filter((f) => {
+        if (typeof f === 'string') return true
+        warnInvalid('messageFilters', f, 'string', 'Value is ignored.')
+        return false
+      })
+      .map(f => f.trim())
+      // empty pattern would match (and swallow) every message
+      .filter(Boolean),
+  }
+}
+
+/**
+ * Load `spec` key from nuxt.config.ts (including extended layers)
+ * and resolve final Nuxt Spec options.
+ * @param {string} [cwd] - directory with nuxt.config.ts
+ * @returns {Promise<import('./options.d.mts').ResolvedNuxtSpecOptions>}
+ */
+export async function loadSpecOptions(cwd = process.cwd()) {
+  if (!specCache.has(cwd)) {
+    specCache.set(cwd, loadNuxtConfig({ cwd })
+      .then(config => config.spec)
+      .catch((error) => {
+        console.warn(`[Nuxt Spec] Failed to read \`spec\` options from nuxt.config: ${error?.message ?? error}`)
+        return undefined
+      }))
+  }
+  return resolveSpecOptions(await specCache.get(cwd))
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+// returns the value if it matches the expected type, otherwise warns and returns undefined
+function checkType(option, value, type) {
+  if (value === undefined) return undefined
+  const matches = type === 'object'
+    ? isObject(value)
+    : type === 'array' ? Array.isArray(value) : typeof value === type
+  if (matches) return value
+  warnInvalid(option, value, type)
+  return undefined
+}
+
+function toOpenMode(option, value) {
+  if (value === undefined) return NUXT_SPEC_DEFAULTS.htmlReport.open
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : value
+  if (HTML_REPORT_OPEN_MODES.includes(normalized)) return normalized
+  warnInvalid(option, value, HTML_REPORT_OPEN_MODES.map(m => `'${m}'`).join(' | '))
+  return NUXT_SPEC_DEFAULTS.htmlReport.open
+}
+
+function warnInvalid(option, value, expected, outcome = 'Falling back to default.') {
+  const message = `[Nuxt Spec] Invalid value ${JSON.stringify(value) ?? String(value)} for \`${option}\` (expected ${expected}). ${outcome}`
+  if (reportedWarnings.has(message)) return
+  reportedWarnings.add(message)
+  console.warn(message)
+}
+
+// unset or empty = not defined, only explicit 'false' disables
+function toBoolean(value) {
+  if (value === undefined || value === '') return undefined
+  return value !== 'false'
+}

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))
+}