nuxt-spec 0.3.3 → 0.4.0-alpha.1

package/bin/update.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 
 import { execSync } from 'node:child_process'
-import { getPackageManager, hasJsonKey, promptUser, showMessage } from 'elrh-cosca'
-import { getPlaywrightInstallCmd, getUpdateCmd } from './helpers/commands.js'
+import {
+  hasJsonKey, promptUser, showMessage,
+} from 'elrh-cosca'
+import {
+  getPlaywrightInstallCmd, getPrepareCmd, getUpdateCmd,
+} from './helpers/commands.js'
 
-const TARGET_VERSION = '0.3.3'
+const TARGET_VERSION = '0.4.0-alpha.1'
 
 /**
  * CLI tool to update existing `nuxt-spec` installation.
@@ -14,60 +18,75 @@ const TARGET_VERSION = '0.3.3'
  * Then it:
  *  1) verifies `nuxt-spec` is present in `package.json` (fails with a hint to run `setup` otherwise)
  *  2) runs the package manager's update command to bump `nuxt-spec` to the latest version
- *  3) run the `playwright-core install` command to ensure the Playwright browser runtimes are up to date
+ *  3) run the `nuxt prepare` command to regenerate types and auto-imports
+ *  4) run the `playwright install` command to ensure the Playwright browser runtimes are up to date
  *
  * @param {boolean} autoRun - Whether to run the update automatically without any prompts (defaults to false).
+ * @param {string} [packageManager] - Package manager to be used (`npm`, `pnpm`, `yarn`, `bun` or `deno`).
  */
-export async function specUpdate(autoRun = false) {
-  showMessage('NUXT SPEC UPDATE')
-  showMessage('This CLI tool will help you update Nuxt Spec in your project.')
-  showMessage('Refer to the documentation for more information.', 2)
+export async function specUpdate(autoRun = false, packageManager) {
+  showMessage({ message: 'NUXT SPEC UPDATE' })
+  showMessage({ message: 'This CLI tool will help you update Nuxt Spec in your project.' })
+  showMessage({ message: 'Refer to the documentation for more information.', linesAfter: 2 })
 
   // fail fast if there is nothing to update
-  const isInstalled = hasJsonKey('package.json', `dependencies.nuxt-spec`)
-    || hasJsonKey('package.json', `devDependencies.nuxt-spec`)
+  const isInstalled = hasJsonKey({ targetFile: 'package.json', jsonKey: `dependencies.nuxt-spec` })
+    || hasJsonKey({ targetFile: 'package.json', jsonKey: `devDependencies.nuxt-spec` })
   if (!isInstalled) {
-    console.error(`'nuxt-spec' was not found in your 'package.json'. Run the 'setup' command first.`)
+    console.error(`[Nuxt Spec] 'nuxt-spec' was not found in your 'package.json'. Run the 'setup' command first.`)
     process.exit(1)
   }
 
-  const isAutoRun = autoRun || await promptUser('Do you want to update everything automatically (no more prompts)?')
-  showMessage('')
-
-  const packageManager = getPackageManager()
+  const isAutoRun = autoRun || await promptUser({ question: '[Nuxt Spec] Do you want to update everything automatically (no more prompts)?' })
+  showMessage({ message: '' })
 
   // 1) run 'update nuxt-spec'
   const updateCmd = getUpdateCmd(packageManager, `nuxt-spec@${TARGET_VERSION}`)
-  const runUpdate = isAutoRun || await promptUser(`This will bump 'nuxt-spec' to version '${TARGET_VERSION}' by running \`${updateCmd}\`. Continue?`)
+  const runUpdate = isAutoRun || await promptUser({ question: `[Nuxt Spec] This will bump 'nuxt-spec' to version '${TARGET_VERSION}' by running \`${updateCmd}\`. Continue?` })
   if (runUpdate) {
     try {
-      showMessage(`Running \`${updateCmd}\`...`)
+      showMessage({ message: `Running \`${updateCmd}\`...` })
       execSync(updateCmd, { stdio: 'inherit' })
     } catch (error) {
-      console.error(`Error running \`${updateCmd}\`:\n`, error.message)
+      console.error(`[Nuxt Spec] Error running \`${updateCmd}\`:\n`, error.message)
     }
   }
 
-  // 2) run 'playwright-core install'
+  // 2) run 'nuxt prepare'
+  const prepareCmd = getPrepareCmd(packageManager)
+  const runPrepare = isAutoRun || await promptUser({ question: `[Nuxt Spec] Nuxt types and auto-imports should be regenerated after the update. Do you want to run \`${prepareCmd}\` now?` })
+  if (runPrepare) {
+    try {
+      showMessage({ message: `Running \`${prepareCmd}\`...` })
+      execSync(prepareCmd, { stdio: 'inherit' })
+    } catch (error) {
+      console.error(`[Nuxt Spec] Error running \`${prepareCmd}\`:\n`, error.message)
+    }
+  }
+
+  // 3) run 'playwright install'
   const playwrightUpdateCmd = getPlaywrightInstallCmd(packageManager)
-  const runPlaywrightUpdate = isAutoRun || await promptUser(`Playwright browser runtimes might need to be updated for e2e tests. Do you want to run \`${playwrightUpdateCmd}\` now?`)
+  const runPlaywrightUpdate = isAutoRun || await promptUser({ question: `[Nuxt Spec] Playwright browser runtimes might need to be updated for e2e tests. Do you want to run \`${playwrightUpdateCmd}\` now?` })
   if (runPlaywrightUpdate) {
     try {
-      showMessage(`Running \`${playwrightUpdateCmd}\`...`)
+      showMessage({ message: `Running \`${playwrightUpdateCmd}\`...` })
       execSync(playwrightUpdateCmd, { stdio: 'inherit' })
     } catch (error) {
-      console.error(`Error running \`${playwrightUpdateCmd}\`:\n`, error.message)
+      console.error(`[Nuxt Spec] Error running \`${playwrightUpdateCmd}\`:\n`, error.message)
     }
   }
 
-  // 3) inform user
-  showMessage('')
-  showMessage('NUXT SPEC UPDATE COMPLETE', 2)
+  // 4) inform user
+  showMessage({ message: '' })
+  showMessage({ message: 'NUXT SPEC UPDATE COMPLETE', linesAfter: 2 })
   if (!runUpdate) {
-    showMessage(`Run \`${updateCmd}\` to update 'nuxt-spec'.`)
+    showMessage({ message: `Run \`${updateCmd}\` to update 'nuxt-spec'.` })
+  }
+  if (!runPrepare) {
+    showMessage({ message: `Run \`${prepareCmd}\` to regenerate the Nuxt types and auto-imports.` })
   }
   if (!runPlaywrightUpdate) {
-    showMessage(`Run \`${playwrightUpdateCmd}\` to update the Playwright browser runtimes for e2e tests.`)
+    showMessage({ message: `Run \`${playwrightUpdateCmd}\` to update the Playwright browser runtimes for e2e tests.` })
   }
 
   // force exit to prevent #20

package/config/index.d.ts

@@ -1,6 +1,8 @@
 import type { UserConfig } from 'vite'
 import type { TestUserConfig } from 'vitest/config'
 
+export type { HtmlReportOpenMode, NuxtSpecOptions } from './utils/options.mjs'
+
 /** Typed Vite configuration object for tests */
 type ExtendedUserConfig = UserConfig & {
   test?: TestUserConfig
@@ -15,7 +17,7 @@ type ExtendedUserConfig = UserConfig & {
  */
 type ProjectsConfig = boolean | {
   default?: boolean
-  node?: boolean
+  unit?: boolean
   nuxt?: boolean
   e2e?: boolean
   browser?: boolean
@@ -23,6 +25,7 @@ type ProjectsConfig = boolean | {
 
 /**
  * Prepare Vitest configuration object - user config merged with nuxt-spec defaults
+ * (defaults are adjusted by `spec` key from nuxt.config.ts and NUXT_SPEC_* env variables)
  * @param userVitestConfig - custom Vitest config passed from the user
  * @param projects - allows fine-grained control over default `test.projects` - see `ProjectsConfig` for details
  * @returns Promise resolving to defu-merged Vitest configuration

package/config/index.mjs

@@ -4,21 +4,25 @@
 
 import { availableParallelism } from 'node:os'
 import { fileURLToPath } from 'node:url'
-import { onConsoleLog } from './utils/warnings.mjs' // filter out unnecessary logs
+import { addMessageFilters, onConsoleLog } from './utils/warnings.mjs' // filter out unnecessary logs
 import { mergeConfig } from './utils/merge.mjs' // defu-based merge function
+import { loadSpecOptions } from './utils/options.mjs' // `spec` key from nuxt.config.ts + NUXT_SPEC_* env variables
+import { nuxtSpecReportPlugin } from './utils/reporter.mjs' // HTML test report
 import { defineConfig } from 'vitest/config'
 import { defineVitestProject } from '@nuxt/test-utils/config'
 import { playwright } from '@vitest/browser-playwright'
 import vue from '@vitejs/plugin-vue'
 
 // absolute paths so it works from within the nuxt-ignis package
-const screenshotReportSetup = fileURLToPath(new URL('../utils/screenshot.ts', import.meta.url))
 const externalPlaywrightSetup = fileURLToPath(new URL('../utils/playwright.ts', import.meta.url))
 
-// external Playwright instance (if configured)
-const externalPlaywright = process.env.NUXT_SPEC_EXTERNAL_PLAYWRIGHT
-
 export async function loadVitestConfig(userVitestConfig, projects = true) {
+  const { externalPlaywright, htmlReport, messageFilters } = await loadSpecOptions()
+
+  // extend array of messages that will be filtered out from the output
+  // with values passed by the user (if any)
+  addMessageFilters(messageFilters)
+
   const baseConfig = {
     test: {
       // filter-out unnecessary console logs coming from Vitest
@@ -31,9 +35,15 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
     },
   }
 
+  // HTML test report for all projects
+  // report is generated unless explicitly disabled
+  if (htmlReport.enabled) {
+    baseConfig.plugins = [nuxtSpecReportPlugin({ open: htmlReport.open })]
+  }
+
   // add proposed projects settings
   // user can control the inclusion via `projects: ProjectsConfig` config object
-  // projects are included by default unless not explicitly disabled
+  // projects are included by default unless explicitly disabled
   if (projects !== false) {
     baseConfig.test.projects = []
 
@@ -50,11 +60,11 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
     }
 
     // proposed setup for Unit tests
-    if (projects.node !== false) {
+    if (projects.unit !== false) {
       baseConfig.test.projects.push({
         extends: true,
         test: {
-          name: 'node',
+          name: 'unit',
           include: ['test/unit/**/*.{test,spec}.ts'],
           environment: 'node',
         },
@@ -83,22 +93,20 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
           name: 'e2e',
           include: ['test/e2e/**/*.{test,spec}.ts'],
           environment: 'node',
-          // create report file for visual regression testing
-          globalSetup: [screenshotReportSetup],
-          // allows connecting to an external Playwright instance,
-          // if NUXT_SPEC_EXTERNAL_PLAYWRIGHT is set
+          // allows connecting to an external Playwright instance (if configured)
           setupFiles: externalPlaywright ? [externalPlaywrightSetup] : [],
+          // setup file will just read the value via `inject()`
+          provide: externalPlaywright ? { nuxtSpecExternalPlaywright: externalPlaywright } : {},
         },
       })
     }
 
     // proposed setup for browser component tests (with Playwright runner)
     if (projects.browser !== false) {
-      // allows connecting to an external Playwright instance,
-      // if NUXT_SPEC_EXTERNAL_PLAYWRIGHT is set
+      // allows connecting to an external Playwright instance (if configured)
       const playwrightConfig = {}
       if (externalPlaywright) {
-        console.log(`[Nuxt Spec - browser] Using external Playwright instance at: ${externalPlaywright}`)
+        console.log(`[Nuxt Spec] Using external Playwright instance for browser tests at: ${externalPlaywright}`)
         playwrightConfig.connectOptions = {
           wsEndpoint: externalPlaywright,
           // this allows reaching caller's localhost from within the external Playwright

package/config/report/report-entry.html

@@ -0,0 +1,6 @@
+<div class="failure">
+  <h2>{{TITLE}}</h2>
+  <p class="location">{{LOCATION}}</p>
+  {{ERRORS}}
+  {{SCREENSHOTS}}
+</div>

package/config/report/report-head.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Nuxt Spec Test Report - {{TIMESTAMP}}</title>
+<style>
+  body { font-family: system-ui, sans-serif; margin: 2rem; background: #f5f5f5; color: #222; }
+  h1 { font-size: 1.4rem; }
+  .summary { font-weight: 700; font-size: 18px; }
+  .summary.passed { color: #0b0; }
+  .summary.failed { color: #b00; }
+  .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 .25rem; }
+  .failure .location { color: #666; font-size: .8rem; margin: 0 0 .75rem; }
+  .failure pre { white-space: pre-wrap; word-break: break-word; font-size: .8rem; margin: 0 0 .75rem; padding: .5rem; background: #fafafa; border: 1px solid #eee; border-radius: 4px; }
+  .failure pre.message { color: #b00; }
+  .failure details summary { cursor: pointer; font-size: .8rem; margin-bottom: .25rem; }
+  .screenshot { margin-top: .75rem; }
+  .screenshot h3 { font-size: .9rem; margin: 0 0 .25rem; }
+  .screenshot .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>Nuxt Spec Test Report - {{TIMESTAMP}}</h1>
+<p class="summary {{STATUS}}">{{SUMMARY}}</p>
+<!-- BEGIN failure entries -->

package/{utils/screenshot/report-entry.html → config/report/report-screenshot.html}

@@ -1,5 +1,5 @@
-<div class="failure">
-  <h2>{{FILE_NAME}}</h2>
+<div class="screenshot">
+  <h3>{{FILE_NAME}}</h3>
   <p class="message">{{MESSAGE}}</p>
   <div class="pair">
     <figure><figcaption>Baseline image</figcaption><img src="{{BASELINE_URI}}" alt="Baseline image for reference"></figure>

package/config/report/report-tail.html

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

package/config/templates/pnpm-workspace.yaml.template

@@ -1,4 +1,19 @@
 # settings for Nuxt & pnpm
 
-# https://pnpm.io/settings#shamefullyhoist
+# https://pnpm.io/settings/node-modules#shamefullyhoist
+# required to handle transitive dependencies 
+# without having to explicitly declare them
 shamefullyHoist: true
+
+# https://pnpm.io/settings/build#allowbuilds
+# pnpm naturally blocks all post-install scripts
+# some are required for development, others are not relevant
+allowBuilds:
+  # provides fallback repair of platform-specific Rust native engine
+  'unrs-resolver': true
+  # allows node-gyp build of associated native binaries from local sources
+  # disabled because it would require an explicit opt-in
+  '@parcel/watcher': false
+  # optimization for CLI usage of 'esbuild'
+  # disabled because its runtime resolves native binaries itself
+  'esbuild': false

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