nuxt-spec 0.3.2 → 0.3.3

package/bin/update.js

@@ -1,75 +1,75 @@
-#!/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'
-
-const TARGET_VERSION = '0.3.2'
-
-/**
- * CLI tool to update existing `nuxt-spec` installation.
- *
- * It first asks whether to run in "auto" mode (no prompts, force = true) or "manual" mode (with prompts, force = false).
- *
- * 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
- *
- * @param {boolean} autoRun - Whether to run the update automatically without any prompts (defaults to false).
- */
-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)
-
-  // fail fast if there is nothing to update
-  const isInstalled = hasJsonKey('package.json', `dependencies.nuxt-spec`)
-    || hasJsonKey('package.json', `devDependencies.nuxt-spec`)
-  if (!isInstalled) {
-    console.error(`'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()
-
-  // 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?`)
-  if (runUpdate) {
-    try {
-      showMessage(`Running \`${updateCmd}\`...`)
-      execSync(updateCmd, { stdio: 'inherit' })
-    } catch (error) {
-      console.error(`Error running \`${updateCmd}\`:\n`, error.message)
-    }
-  }
-
-  // 2) run 'playwright-core 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?`)
-  if (runPlaywrightUpdate) {
-    try {
-      showMessage(`Running \`${playwrightUpdateCmd}\`...`)
-      execSync(playwrightUpdateCmd, { stdio: 'inherit' })
-    } catch (error) {
-      console.error(`Error running \`${playwrightUpdateCmd}\`:\n`, error.message)
-    }
-  }
-
-  // 3) inform user
-  showMessage('')
-  showMessage('NUXT SPEC UPDATE COMPLETE', 2)
-  if (!runUpdate) {
-    showMessage(`Run \`${updateCmd}\` to update 'nuxt-spec'.`)
-  }
-  if (!runPlaywrightUpdate) {
-    showMessage(`Run \`${playwrightUpdateCmd}\` to update the Playwright browser runtimes for e2e tests.`)
-  }
-
-  // force exit to prevent #20
-  process.exit(0)
-}
+#!/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'
+
+const TARGET_VERSION = '0.3.3'
+
+/**
+ * CLI tool to update existing `nuxt-spec` installation.
+ *
+ * It first asks whether to run in "auto" mode (no prompts, force = true) or "manual" mode (with prompts, force = false).
+ *
+ * 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
+ *
+ * @param {boolean} autoRun - Whether to run the update automatically without any prompts (defaults to false).
+ */
+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)
+
+  // fail fast if there is nothing to update
+  const isInstalled = hasJsonKey('package.json', `dependencies.nuxt-spec`)
+    || hasJsonKey('package.json', `devDependencies.nuxt-spec`)
+  if (!isInstalled) {
+    console.error(`'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()
+
+  // 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?`)
+  if (runUpdate) {
+    try {
+      showMessage(`Running \`${updateCmd}\`...`)
+      execSync(updateCmd, { stdio: 'inherit' })
+    } catch (error) {
+      console.error(`Error running \`${updateCmd}\`:\n`, error.message)
+    }
+  }
+
+  // 2) run 'playwright-core 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?`)
+  if (runPlaywrightUpdate) {
+    try {
+      showMessage(`Running \`${playwrightUpdateCmd}\`...`)
+      execSync(playwrightUpdateCmd, { stdio: 'inherit' })
+    } catch (error) {
+      console.error(`Error running \`${playwrightUpdateCmd}\`:\n`, error.message)
+    }
+  }
+
+  // 3) inform user
+  showMessage('')
+  showMessage('NUXT SPEC UPDATE COMPLETE', 2)
+  if (!runUpdate) {
+    showMessage(`Run \`${updateCmd}\` to update 'nuxt-spec'.`)
+  }
+  if (!runPlaywrightUpdate) {
+    showMessage(`Run \`${playwrightUpdateCmd}\` to update the Playwright browser runtimes for e2e tests.`)
+  }
+
+  // force exit to prevent #20
+  process.exit(0)
+}

package/config/index.d.ts

@@ -1,33 +1,33 @@
-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
-  node?: 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'
+
+/** 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
+  node?: 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>

package/config/index.mjs

@@ -1,114 +1,132 @@
-// 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 path so it works from nuxt-ignis package
-const screenshotReportSetup = fileURLToPath(new URL('../utils/screenshot.ts', import.meta.url))
-
-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.node !== false) {
-      baseConfig.test.projects.push({
-        extends: true,
-        test: {
-          name: 'node',
-          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],
-        },
-      })
-    }
-
-    // proposed setup for browser component tests (with Playwright runner)
-    if (projects.browser !== false) {
-      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 - add others manually if needed
-          browser: {
-            provider: playwright(),
-            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 { 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.node !== false) {
+      baseConfig.test.projects.push({
+        extends: true,
+        test: {
+          name: 'node',
+          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))
+}

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

@@ -1,4 +1,4 @@
-# settings for Nuxt & pnpm
-
-# https://pnpm.io/settings#shamefullyhoist
-shamefullyHoist: true
+# settings for Nuxt & pnpm
+
+# https://pnpm.io/settings#shamefullyhoist
+shamefullyHoist: true

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/warnings.mjs

@@ -1,33 +1,33 @@
-const messageFilters = [
-  // Node+Windows false positive
-  // https://github.com/nuxt/icon/issues/140
-  'Use of deprecated trailing slash pattern mapping',
-  // remove once Vue stops considering <Suspense> experimental
-  '<Suspense> is an experimental feature',
-  // merge defaults with user-defined filters from NUXT_SPEC_MESSAGE_FILTERS env variable
-  ...(process.env.NUXT_SPEC_MESSAGE_FILTERS
-    ? process.env.NUXT_SPEC_MESSAGE_FILTERS.split(',')
-    : []),
-]
-
-// 1) filter-out unnecessary stderr/stdout logs coming from Vitest
-// (applied as side-effect on import)
-
-const _stderrWrite = process.stderr.write.bind(process.stderr)
-process.stderr.write = (chunk, ...args) => {
-  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
-  return _stderrWrite(chunk, ...args)
-}
-
-const _stdoutWrite = process.stdout.write.bind(process.stdout)
-process.stdout.write = (chunk, ...args) => {
-  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
-  return _stdoutWrite(chunk, ...args)
-}
-
-// 2) filter-out unnecessary console logs coming from Vitest
-// (used as Vitest onConsoleLog hook)
-
-export function onConsoleLog(log) {
-  if (messageFilters.some(f => log.includes(f))) return false
-}
+const messageFilters = [
+  // Node+Windows false positive
+  // https://github.com/nuxt/icon/issues/140
+  'Use of deprecated trailing slash pattern mapping',
+  // remove once Vue stops considering <Suspense> experimental
+  '<Suspense> is an experimental feature',
+  // merge defaults with user-defined filters from NUXT_SPEC_MESSAGE_FILTERS env variable
+  ...(process.env.NUXT_SPEC_MESSAGE_FILTERS
+    ? process.env.NUXT_SPEC_MESSAGE_FILTERS.split(',')
+    : []),
+]
+
+// 1) filter-out unnecessary stderr/stdout logs coming from Vitest
+// (applied as side-effect on import)
+
+const _stderrWrite = process.stderr.write.bind(process.stderr)
+process.stderr.write = (chunk, ...args) => {
+  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
+  return _stderrWrite(chunk, ...args)
+}
+
+const _stdoutWrite = process.stdout.write.bind(process.stdout)
+process.stdout.write = (chunk, ...args) => {
+  if (typeof chunk === 'string' && messageFilters.some(f => chunk.includes(f))) return true
+  return _stdoutWrite(chunk, ...args)
+}
+
+// 2) filter-out unnecessary console logs coming from Vitest
+// (used as Vitest onConsoleLog hook)
+
+export function onConsoleLog(log) {
+  if (messageFilters.some(f => log.includes(f))) return false
+}