nuxt-spec 0.4.0-alpha.1 → 0.4.0-alpha.3

package/config/report/report-screenshot.html

@@ -1,8 +1,8 @@
-<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>
+<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

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

package/config/templates/.github/workflows/ci-test-verify.yml.template

@@ -0,0 +1,68 @@
+# GitHub Actions workflow (scaffolded by Nuxt Spec) to run test suite in a pinned Playwright container for reproducible results.
+# Triggered automatically on push/pull requests to default branch with possible manual dispatch.
+# Uses pnpm - the pnpm store is cached so subsequent `pnpm install` runs reuse downloaded deps.
+# If tests fail, `ci-test-report` artifact (HTML report, current screenshots, Vitest attachments) is uploaded for inspection.
+# NOTE: commits pushed by "update baselines" workflow don't trigger this workflow - dispatch it manually afterwards.
+
+name: Nuxt Spec CI Tests (verify)
+
+on:
+  push:
+    branches: [__DEFAULT_BRANCH__]
+  pull_request:
+    branches: [__DEFAULT_BRANCH__]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-test-verify-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    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
+
+      - 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: Run tests
+        run: pnpm test
+
+      - name: Upload test report
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: ci-test-report-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            test/__reports__
+            **/__current__/**
+            .vitest/attachments
+            !**/node_modules/**
+          include-hidden-files: true
+          if-no-files-found: ignore
+          retention-days: 14

package/config/templates/.gitlab/ci/ci-test-update.yml.template

@@ -0,0 +1,69 @@
+# GitLab CI/CD job (scaffolded by Nuxt Spec) to update test baselines (manually triggered).
+# Start it via "Build > Pipelines > Run pipeline" on selected branch with `NUXT_SPEC_UPDATE_BASELINES` set to `true`.
+# Runs in the same pinned Playwright container as "verify" job.
+# Updated baselines (`__baseline__`, `__screenshots__`) and snapshots (`__snapshots__`) are committed back to the selected branch.
+# If the push is rejected (e.g. protected branch), a new branch with a merge request is created instead.
+# PREREQUISITE: project access token with `write_repository` scope stored as masked CI/CD variable `NUXT_SPEC_CI_TOKEN`
+#   (CI_JOB_TOKEN cannot be used for pushing; the token role decides whether it may push into protected branches).
+
+variables:
+  NUXT_SPEC_UPDATE_BASELINES:
+    value: "false"
+    options: ["false", "true"]
+    description: Set to "true" to regenerate and commit test baselines (Nuxt Spec).
+
+ci-test-update:
+  stage: test
+  # must match `playwright` dependency version
+  image: mcr.microsoft.com/playwright:v__PLAYWRIGHT_VERSION__-jammy
+  resource_group: ci-test-update-$CI_COMMIT_REF_SLUG
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "web" && $NUXT_SPEC_UPDATE_BASELINES == "true" && $CI_COMMIT_BRANCH
+  variables:
+    PNPM_STORE_DIR: $CI_PROJECT_DIR/.pnpm-store
+  cache:
+    key:
+      prefix: pnpm
+      files:
+        - pnpm-lock.yaml
+    paths:
+      - .pnpm-store/
+  before_script:
+    - ': "${NUXT_SPEC_CI_TOKEN:?CI/CD variable NUXT_SPEC_CI_TOKEN (project access token with write_repository scope) is required}"'
+    - corepack enable
+    - pnpm install --frozen-lockfile --store-dir "$PNPM_STORE_DIR"
+    - pnpm store prune --store-dir "$PNPM_STORE_DIR"
+  script:
+    - pnpm test-u
+    - |
+      set -eu
+
+      git config user.name "$GITLAB_USER_NAME"
+      git config user.email "$GITLAB_USER_EMAIL"
+
+      # `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"
+
+      PUSH_URL="${CI_SERVER_PROTOCOL}://oauth2:${NUXT_SPEC_CI_TOKEN}@${CI_SERVER_HOST}:${CI_SERVER_PORT}/${CI_PROJECT_PATH}.git"
+      if git push "$PUSH_URL" "HEAD:refs/heads/$CI_COMMIT_BRANCH"; then
+        echo "Updated baselines pushed to '$CI_COMMIT_BRANCH'."
+        exit 0
+      fi
+
+      echo "Push to '$CI_COMMIT_BRANCH' was rejected (e.g. protected branch) - creating merge request..."
+      NEW_BRANCH="ci-test/update-$(date +%Y%m%d%H%M%S)"
+      git push "$PUSH_URL" "HEAD:refs/heads/$NEW_BRANCH" \
+        -o merge_request.create \
+        -o merge_request.target="$CI_COMMIT_BRANCH" \
+        -o merge_request.title="test(ci): update test baselines" \
+        -o merge_request.description="Test baselines update triggered by pipeline #$CI_PIPELINE_IID against branch \`$CI_COMMIT_BRANCH\`."

package/config/templates/.gitlab/ci/ci-test-verify.yml.template

@@ -0,0 +1,41 @@
+# GitLab CI/CD job (scaffolded by Nuxt Spec) to run test suite in a pinned Playwright container for reproducible results.
+# Triggered automatically on push to default branch and on merge requests targeting it.
+# Can be started manually via "Build > Pipelines > Run pipeline" (with `NUXT_SPEC_UPDATE_BASELINES` left as `false`).
+# Uses pnpm - the pnpm store is cached so subsequent `pnpm install` runs reuse downloaded deps.
+# If tests fail, artifacts (HTML report, current screenshots, Vitest attachments) are kept for inspection.
+
+ci-test-verify:
+  stage: test
+  # must match `playwright` dependency version
+  image: mcr.microsoft.com/playwright:v__PLAYWRIGHT_VERSION__-jammy
+  interruptible: true
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event" && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == $CI_DEFAULT_BRANCH
+    - if: $CI_PIPELINE_SOURCE == "web" && $NUXT_SPEC_UPDATE_BASELINES != "true"
+  variables:
+    PNPM_STORE_DIR: $CI_PROJECT_DIR/.pnpm-store
+  cache:
+    key:
+      prefix: pnpm
+      files:
+        - pnpm-lock.yaml
+    paths:
+      - .pnpm-store/
+  before_script:
+    - corepack enable
+    - pnpm install --frozen-lockfile --store-dir "$PNPM_STORE_DIR"
+    - pnpm store prune --store-dir "$PNPM_STORE_DIR"
+  script:
+    - pnpm test
+  artifacts:
+    name: ci-test-report-$CI_PIPELINE_ID
+    when: on_failure
+    expire_in: 14 days
+    paths:
+      - test/__reports__/
+      - "**/__current__/"
+      - .vitest/attachments/
+    exclude:
+      - node_modules/**/*
+      - .pnpm-store/**/*

package/config/templates/.gitlab-ci.yml.template

@@ -0,0 +1,6 @@
+# GitLab CI/CD configuration (scaffolded by Nuxt Spec).
+# Nuxt Spec test jobs are defined in the included files.
+
+include:
+  - local: .gitlab/ci/ci-test-verify.yml
+  - local: .gitlab/ci/ci-test-update.yml

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

@@ -1,19 +1,19 @@
-# settings for Nuxt & pnpm
-
-# 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
+# settings for Nuxt & pnpm
+
+# 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/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

@@ -1,59 +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>
+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>