nuxt-spec 0.3.4 → 0.4.0-alpha.2

package/bin/helpers/git.js

@@ -0,0 +1,73 @@
+import { execFileSync } from 'node:child_process'
+
+export const FALLBACK_DEFAULT_BRANCH = 'main'
+
+// run a read-only git command, returning trimmed stdout or `undefined` on failure
+function git(...args) {
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined
+  } catch {
+    return undefined
+  }
+}
+
+function hasRef(ref) {
+  try {
+    execFileSync('git', ['show-ref', '--verify', '--quiet', ref], { stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function isGitRepo() {
+  return git('rev-parse', '--is-inside-work-tree') === 'true'
+}
+
+/**
+ * Resolve the default branch of the Git repository in the current working directory.
+ *
+ * Tries (in order):
+ *  1) HEAD of `origin` remote (or the first available remote) - set when cloned or via `git remote set-head <remote> --auto`
+ *  2) existing local or remote-tracking `main` or `master` branch
+ *  3) the only local branch, or current branch if there are no commits yet
+ *  4) `init.defaultBranch` from Git config
+ *
+ * @returns {{ branch: string, source: string }} resolved branch name and description of where it came from
+ */
+export function resolveDefaultBranch() {
+  if (isGitRepo()) {
+    const remotes = git('remote')?.split(/\r?\n/) ?? []
+    const remote = remotes.includes('origin') ? 'origin' : remotes[0]
+    if (remote) {
+      const remoteHead = git('symbolic-ref', '--quiet', '--short', `refs/remotes/${remote}/HEAD`)
+      if (remoteHead?.startsWith(`${remote}/`)) {
+        return { branch: remoteHead.slice(remote.length + 1), source: `HEAD of '${remote}' remote` }
+      }
+    }
+
+    for (const candidate of ['main', 'master']) {
+      if (hasRef(`refs/heads/${candidate}`) || (remote && hasRef(`refs/remotes/${remote}/${candidate}`))) {
+        return { branch: candidate, source: 'existing branch' }
+      }
+    }
+
+    const localBranches = git('for-each-ref', '--format=%(refname:short)', 'refs/heads')?.split(/\r?\n/) ?? []
+    if (localBranches.length === 1) {
+      return { branch: localBranches[0], source: 'the only local branch' }
+    }
+    if (localBranches.length === 0) {
+      const unbornHead = git('symbolic-ref', '--quiet', '--short', 'HEAD')
+      if (unbornHead) {
+        return { branch: unbornHead, source: 'current branch of repository without commits' }
+      }
+    }
+  }
+
+  const configured = git('config', '--get', 'init.defaultBranch')
+  if (configured) {
+    return { branch: configured, source: 'Git config \'init.defaultBranch\'' }
+  }
+
+  return { branch: FALLBACK_DEFAULT_BRANCH, source: 'fallback value' }
+}

package/config/index.d.ts

@@ -1,33 +1,36 @@
-import type { UserConfig } from 'vite'
-import type { TestUserConfig } from 'vitest/config'
-
-/** Typed Vite configuration object for tests */
-type ExtendedUserConfig = UserConfig & {
-  test?: TestUserConfig
-}
-
-/**
- * Allows fine-grained control over default Vitest `projects`.
- *
- * By default, everything is included.
- * If set to `false`, `test.projects` key is not merged at all.
- * If set to object, specific projects can be omitted by setting respective key to `false`.
- */
-type ProjectsConfig = boolean | {
-  default?: boolean
-  unit?: boolean
-  nuxt?: boolean
-  e2e?: boolean
-  browser?: boolean
-}
-
-/**
- * Prepare Vitest configuration object - user config merged with nuxt-spec defaults
- * @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
- */
-export declare function loadVitestConfig(
-  userVitestConfig: ExtendedUserConfig,
-  projects?: ProjectsConfig,
-): Promise<ExtendedUserConfig>
+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
+}
+
+/**
+ * Allows fine-grained control over default Vitest `projects`.
+ *
+ * By default, everything is included.
+ * If set to `false`, `test.projects` key is not merged at all.
+ * If set to object, specific projects can be omitted by setting respective key to `false`.
+ */
+type ProjectsConfig = boolean | {
+  default?: boolean
+  unit?: boolean
+  nuxt?: boolean
+  e2e?: boolean
+  browser?: 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
+ */
+export declare function loadVitestConfig(
+  userVitestConfig: ExtendedUserConfig,
+  projects?: ProjectsConfig,
+): Promise<ExtendedUserConfig>

package/config/index.mjs

@@ -1,132 +1,147 @@
-// this is the default Vitest config object
-// based on https://nuxt.com/docs/4.x/getting-started/testing#setup
-// `projects=false` can be used to suspend the default usage of "projects" in Vitest config
-
-import { availableParallelism } from 'node:os'
-import { fileURLToPath } from 'node:url'
-import { onConsoleLog } from './utils/warnings.mjs' // filter out unnecessary logs
-import { mergeConfig } from './utils/merge.mjs' // defu-based merge function
-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 baseConfig = {
-    test: {
-      // filter-out unnecessary console logs coming from Vitest
-      // when the import is resolved, unnecessary stderr logs are also filtered-out
-      // as a side-effect
-      onConsoleLog,
-      // Vitest defaults to 5 which might be unnecessarily restrictive
-      // if the host machine can support more
-      maxConcurrency: availableParallelism() / 2,
-    },
-  }
-
-  // add proposed projects settings
-  // user can control the inclusion via `projects: ProjectsConfig` config object
-  // projects are included by default unless not explicitly disabled
-  if (projects !== false) {
-    baseConfig.test.projects = []
-
-    // default fallback to catch tests directly in /test folder
-    if (projects.default !== false) {
-      baseConfig.test.projects.push({
-        extends: true,
-        test: {
-          name: 'default',
-          include: ['{test,tests}/**/*.{test,spec}.ts', '!test/{browser,e2e,nuxt,unit}/**'],
-          environment: 'node',
-        },
-      })
-    }
-
-    // proposed setup for Unit tests
-    if (projects.unit !== false) {
-      baseConfig.test.projects.push({
-        extends: true,
-        test: {
-          name: 'unit',
-          include: ['test/unit/**/*.{test,spec}.ts'],
-          environment: 'node',
-        },
-      })
-    }
-
-    // proposed setup for Nuxt component tests
-    if (projects.nuxt !== false) {
-      baseConfig.test.projects.push(
-        await defineVitestProject({
-          extends: true,
-          test: {
-            name: 'nuxt',
-            include: ['test/nuxt/**/*.{test,spec}.ts'],
-            environment: 'nuxt',
-          },
-        }),
-      )
-    }
-
-    // proposed setup for classic E2E tests (node-based, using @nuxt/test-utils)
-    if (projects.e2e !== false) {
-      baseConfig.test.projects.push({
-        extends: true,
-        test: {
-          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
-          setupFiles: externalPlaywright ? [externalPlaywrightSetup] : [],
-        },
-      })
-    }
-
-    // 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
-      const playwrightConfig = {}
-      if (externalPlaywright) {
-        console.log(`[Nuxt Spec - browser] Using external Playwright instance at: ${externalPlaywright}`)
-        playwrightConfig.connectOptions = {
-          wsEndpoint: externalPlaywright,
-          // this allows reaching caller's localhost from within the external Playwright
-          exposeNetwork: '<loopback>',
-        }
-      }
-      baseConfig.test.projects.push({
-        extends: true,
-        // vue plugin is required for proper imports resolution
-        plugins: [vue()],
-        test: {
-          name: 'browser',
-          include: ['test/browser/**/*.{test,spec}.ts'],
-          environment: 'node',
-          // only chromium browser by default - add others manually if needed
-          browser: {
-            provider: playwright(playwrightConfig),
-            enabled: true,
-            headless: true,
-            instances: [{
-              browser: 'chromium',
-              viewport: { width: 1280, height: 720 },
-            }],
-          },
-        },
-      })
-    }
-  }
-
-  return mergeConfig(userVitestConfig, defineConfig(baseConfig))
-}
+// this is the default Vitest config object
+// based on https://nuxt.com/docs/4.x/getting-started/testing#setup
+// `projects=false` can be used to suspend the default usage of "projects" in Vitest config
+
+import { availableParallelism } from 'node:os'
+import { fileURLToPath } from 'node:url'
+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 externalPlaywrightSetup = fileURLToPath(new URL('../utils/playwright.ts', import.meta.url))
+
+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
+      // when the import is resolved, unnecessary stderr logs are also filtered-out
+      // as a side-effect
+      onConsoleLog,
+      // Vitest defaults to 5 which might be unnecessarily restrictive
+      // if the host machine can support more
+      maxConcurrency: availableParallelism() / 2,
+      // coverage is NOT enabled by default
+      // (use `test-c` command or `--coverage` flag)
+      // Bun runtime lacks support for the V8 provider
+      // (`bun run` without `--bun` still runs Vitest in Node, where V8 works)
+      coverage: {
+        provider: process.versions.bun ? 'istanbul' : 'v8',
+      },
+    },
+  }
+
+  // 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 explicitly disabled
+  if (projects !== false) {
+    baseConfig.test.projects = []
+
+    // default fallback to catch tests directly in /test folder
+    if (projects.default !== false) {
+      baseConfig.test.projects.push({
+        extends: true,
+        test: {
+          name: 'default',
+          include: ['{test,tests}/**/*.{test,spec}.ts', '!test/{browser,e2e,nuxt,unit}/**'],
+          environment: 'node',
+        },
+      })
+    }
+
+    // proposed setup for Unit tests
+    if (projects.unit !== false) {
+      baseConfig.test.projects.push({
+        extends: true,
+        test: {
+          name: 'unit',
+          include: ['test/unit/**/*.{test,spec}.ts'],
+          environment: 'node',
+        },
+      })
+    }
+
+    // proposed setup for Nuxt component tests
+    if (projects.nuxt !== false) {
+      baseConfig.test.projects.push(
+        await defineVitestProject({
+          extends: true,
+          test: {
+            name: 'nuxt',
+            include: ['test/nuxt/**/*.{test,spec}.ts'],
+            environment: 'nuxt',
+          },
+        }),
+      )
+    }
+
+    // proposed setup for classic E2E tests (node-based, using @nuxt/test-utils)
+    if (projects.e2e !== false) {
+      baseConfig.test.projects.push({
+        extends: true,
+        test: {
+          name: 'e2e',
+          include: ['test/e2e/**/*.{test,spec}.ts'],
+          environment: 'node',
+          // 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 configured)
+      const playwrightConfig = {}
+      if (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
+          exposeNetwork: '<loopback>',
+        }
+      }
+      baseConfig.test.projects.push({
+        extends: true,
+        // vue plugin is required for proper imports resolution
+        plugins: [vue()],
+        test: {
+          name: 'browser',
+          include: ['test/browser/**/*.{test,spec}.ts'],
+          environment: 'node',
+          // only chromium browser by default - add others manually if needed
+          browser: {
+            provider: playwright(playwrightConfig),
+            enabled: true,
+            headless: true,
+            instances: [{
+              browser: 'chromium',
+              viewport: { width: 1280, height: 720 },
+            }],
+          },
+        },
+      })
+    }
+  }
+
+  return mergeConfig(userVitestConfig, defineConfig(baseConfig))
+}

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,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="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>
+    <figure><figcaption>Actual screenshot</figcaption><img src="{{ACTUAL_URI}}" alt="Actual screenshot taken"></figure>
+  </div>
+</div>

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/.github/workflows/ci-test-update.yml.template

@@ -0,0 +1,105 @@
+# GitHub Actions workflow (scaffolded by Nuxt Spec) to update test baselines (manually triggered).
+# Runs in the same pinned Playwright container as "verify" workflow.
+# Updated baselines (`__baseline__`, `__screenshots__`) and snapshots (`__snapshots__`) are committed back to the dispatched branch.
+# If the push is rejected (e.g. protected branch), a new branch with a pull request is created instead.
+# PREREQUISITE: for the pull request fallback, enable
+#   "Settings > Actions > General > Allow GitHub Actions to create and approve pull requests".
+# NOTE: commits and pull requests created via GITHUB_TOKEN don't trigger other workflows - run "verify" manually afterwards.
+
+name: Nuxt Spec CI Tests (update baselines)
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-test-update-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    container:
+      # must match `playwright` dependency version
+      image: mcr.microsoft.com/playwright:v__PLAYWRIGHT_VERSION__-jammy
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.ref_name }}
+
+      - name: Enable pnpm via corepack
+        run: corepack enable
+
+      - name: Resolve pnpm store path
+        id: pnpm-store
+        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache pnpm store
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: pnpm-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: pnpm-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Prune pnpm store
+        run: pnpm store prune
+
+      - name: Regenerate test baselines
+        run: pnpm test-u
+
+      - name: Commit updated baselines
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          REF_NAME: ${{ github.ref_name }}
+          RUN_NUMBER: ${{ github.run_number }}
+        run: |
+          set -eu
+
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # `git add` fails on a glob without matches, `git ls-files` doesn't
+          git ls-files -z -m -d -o --exclude-standard -- \
+            ':(glob)**/__baseline__/**' \
+            ':(glob)**/__screenshots__/**' \
+            ':(glob)**/__snapshots__/**' \
+            | xargs -0 -r git add -A --
+          if git diff --cached --quiet; then
+            echo "No baseline changes to commit."
+            exit 0
+          fi
+
+          git commit -m "test(ci): update test baselines"
+
+          if git push origin "HEAD:$REF_NAME"; then
+            echo "Updated baselines pushed to '$REF_NAME'."
+            exit 0
+          fi
+
+          echo "Push to '$REF_NAME' was rejected (e.g. protected branch) - creating pull request..."
+          export NEW_BRANCH="ci-test/update-$(date +%Y%m%d%H%M%S)"
+          git push origin "HEAD:refs/heads/$NEW_BRANCH"
+          BODY=$(node -e '
+            const { NEW_BRANCH, REF_NAME, RUN_NUMBER } = process.env
+            console.log(JSON.stringify({
+              title: "test(ci): update test baselines",
+              head: NEW_BRANCH,
+              base: REF_NAME,
+              body: `Test baselines update triggered on run #${RUN_NUMBER} against branch \`${REF_NAME}\`.`,
+            }))')
+          curl -sS -X POST \
+            -H "Authorization: Bearer $GH_TOKEN" \
+            -H "Accept: application/vnd.github+json" \
+            -H "Content-Type: application/json" \
+            -d "$BODY" \
+            --fail-with-body \
+            "https://api.github.com/repos/$REPO/pulls"