nuxt-spec 0.3.2 → 0.3.4

package/app/components/NuxtSpecTestComponent.vue

@@ -1,5 +1,5 @@
 <template>
-  <div style="margin: 1rem 0; padding: 0.5rem; border: 1px solid black;">
+  <div data-testid="test-component" style="margin: 1rem 0; padding: 0.5rem; border: 1px solid black;">
     {{ text }}
   </div>
 </template>

package/bin/cli.js

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
 
-import { getCmd } from './helpers/commands.js'
+import { getCmd, resolvePackageManager } from './helpers/commands.js'
 
 /**
  * CLI tool to scaffold necessary adjustments in project folder.
  *
  * Allows `setup` or `update` to be passed as parameter.
  *
- * Second parameter might be a boolean to indicate auto mode
+ * Second (optional) parameter might be a boolean to indicate auto mode
  * (no prompts, force = true) or manual mode (with prompts, force = false).
+ *
+ * Third (optional) parameter allows explicitly passing the package manager
+ * (`npm`, `pnpm`, `yarn`, `bun` or `deno`), bypassing auto-detection.
  */
 
 // get parameters passed by user
@@ -19,19 +22,22 @@ const args = process.argv.slice(2);
 (async () => {
   let status = 0
   try {
+    const packageManager = resolvePackageManager(args[2])
+    // CLI args are always strings, so 'false' must be parsed explicitly rather than treated as truthy
+    const autoRun = args[1] === 'true'
     switch (args[0]) {
       case 'setup':
-        await (await import('./setup.js')).specSetup(args[1] || false)
+        await (await import('./setup.js')).specSetup(autoRun, packageManager)
         break
       case 'update':
-        await (await import('./update.js')).specUpdate(args[1] || false)
+        await (await import('./update.js')).specUpdate(autoRun, packageManager)
         break
       default:
-        console.log(`Usage: \`${getCmd()} setup [true|false]\` or \`${getCmd()} update [true|false]\``)
+        console.log(`Usage: \`${getCmd(packageManager)} setup [true|false] [npm|pnpm|yarn|bun|deno]\` or \`${getCmd(packageManager)} update [true|false] [npm|pnpm|yarn|bun|deno]\``)
         status = 1
     }
   } catch (error) {
-    console.error('Setup failed:', error.message)
+    console.error('nuxt-spec CLI failed:', error.message)
     status = 1
   }
   process.exit(status)

package/bin/helpers/commands.js

@@ -1,9 +1,22 @@
 import { getPackageManager } from 'elrh-cosca'
 
+export const SUPPORTED_PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun', 'deno']
+
+// get the package manager name for usage in commands
+// explicit override takes precedence over auto-detection
+export function resolvePackageManager(override) {
+  if (override) {
+    if (!SUPPORTED_PACKAGE_MANAGERS.includes(override)) {
+      throw new Error(`Unsupported package manager '${override}'. Use one of: ${SUPPORTED_PACKAGE_MANAGERS.join(', ')}`)
+    }
+    return override
+  }
+  return getPackageManager()
+}
+
 // use nuxt-spec CLI tool
-export function getCmd() {
+export function getCmd(packageManager) {
   const command = 'nuxt-spec'
-  const packageManager = getPackageManager()
   switch (packageManager) {
     case 'pnpm':
       return `pnpx ${command}`
@@ -24,19 +37,36 @@ export function getUpdateCmd(packageManager, target) {
     case 'pnpm':
       return `pnpm update ${target}`
     case 'yarn':
-      return `yarn upgrade ${target}`
+      return `yarn up ${target}`
     case 'bun':
       return `bun update ${target}`
     case 'deno':
       return `deno add npm:${target}`
     default:
-      return `npm update ${target}`
+      return `npm install ${target}`
+  }
+}
+
+// generate Nuxt types and auto-imports
+export function getPrepareCmd(packageManager) {
+  const command = 'nuxt prepare'
+  switch (packageManager) {
+    case 'pnpm':
+      return `pnpm exec ${command}`
+    case 'yarn':
+      return `yarn ${command}`
+    case 'bun':
+      return `bunx ${command}`
+    case 'deno':
+      return `deno run -A npm:${command}`
+    default:
+      return `npx ${command}`
   }
 }
 
 // install/update playwright
 export function getPlaywrightInstallCmd(packageManager) {
-  const command = 'playwright-core install'
+  const command = 'playwright install'
   switch (packageManager) {
     case 'pnpm':
       return `pnpm exec ${command}`

package/bin/setup.js

@@ -2,13 +2,15 @@
 
 import { execSync } from 'node:child_process'
 import {
-  createFileFromWebTemplate, deletePath, getPackageManager, hasJsonKey,
+  createFileFromWebTemplate, deletePath, hasJsonKey,
   pathExists, promptUser, removeFromJsonFile, showMessage,
   updateConfigFile, updateJsonFile, updateTextFile,
 } from 'elrh-cosca'
-import { getPlaywrightInstallCmd } from './helpers/commands.js'
+import {
+  getPlaywrightInstallCmd, getPrepareCmd,
+} from './helpers/commands.js'
 
-const TARGET_VERSION = '0.3.2'
+const TARGET_VERSION = '0.3.4'
 
 /**
  * CLI tool to scaffold necessary adjustments in project folder.
@@ -25,11 +27,13 @@ const TARGET_VERSION = '0.3.2'
  *  7) creates sample test files
  *  8) clear node_modules and lock file(s)
  *  9) run install command
- * 10) run Playwright setup command
+ * 10) run Nuxt prepare command to generate types and auto-imports
+ * 11) run Playwright setup command
  *
  * @param {boolean} autoRun - Whether to run the setup automatically without any prompts (defaults to false).
+ * @param {string} [packageManager] - Package manager to be used (`npm`, `pnpm`, `yarn`, `bun` or `deno`).
  */
-export async function specSetup(autoRun = false) {
+export async function specSetup(autoRun = false, packageManager) {
   showMessage('NUXT SPEC SETUP')
   showMessage('This CLI tool will help you include Nuxt Spec in your project.')
   showMessage('Refer to the documentation for more information.', 2)
@@ -37,8 +41,6 @@ export async function specSetup(autoRun = false) {
   const isAutoRun = autoRun || await promptUser('Do you want to set everything up automatically (no more prompts)?')
   showMessage('')
 
-  const packageManager = getPackageManager()
-
   // 1) manage dependencies in package.json
 
   // add nuxt-spec
@@ -243,7 +245,19 @@ export async function specSetup(autoRun = false) {
     }
   }
 
-  // 10) run Playwright browser install command
+  // 10) run Nuxt prepare command to generate types and auto-imports
+  const prepareCmd = getPrepareCmd(packageManager)
+  const runPrepare = isAutoRun || await promptUser(`Nuxt needs to generate types and auto-imports before the project is fully usable. Do you want to run \`${prepareCmd}\` now?`)
+  if (runPrepare) {
+    try {
+      showMessage(`Running \`${prepareCmd}\`...`)
+      execSync(prepareCmd, { stdio: 'inherit' })
+    } catch (error) {
+      console.error(`Error running \`${prepareCmd}\`:\n`, error.message)
+    }
+  }
+
+  // 11) run Playwright browser install command
   const playwrightInstallCmd = getPlaywrightInstallCmd(packageManager)
   const runPlaywrightInstall = isAutoRun || await promptUser(`Playwright browser runtimes might need to be installed locally for e2e tests. Do you want to run \`${playwrightInstallCmd}\` now?`)
   if (runPlaywrightInstall) {
@@ -255,12 +269,15 @@ export async function specSetup(autoRun = false) {
     }
   }
 
-  // 11) inform user
+  // 12) inform user
   showMessage('')
   showMessage('NUXT SPEC SETUP COMPLETE', 2)
   if (!runInstall) {
     showMessage(`Proceed with \`${packageManager} install\` to install dependencies.`)
   }
+  if (!runPrepare) {
+    showMessage(`Run \`${prepareCmd}\` to generate the required Nuxt types and auto-imports.`)
+  }
   if (!runPlaywrightInstall) {
     showMessage(`Run \`${playwrightInstallCmd}\` to setup the Playwright browser runtimes for e2e tests.`)
   }

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.2'
+const TARGET_VERSION = '0.3.4'
 
 /**
  * CLI tool to update existing `nuxt-spec` installation.
@@ -14,11 +18,13 @@ const TARGET_VERSION = '0.3.2'
  * 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) {
+export async function specUpdate(autoRun = false, packageManager) {
   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)
@@ -34,8 +40,6 @@ export async function specUpdate(autoRun = false) {
   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?`)
@@ -48,7 +52,19 @@ export async function specUpdate(autoRun = false) {
     }
   }
 
-  // 2) run 'playwright-core install'
+  // 2) run 'nuxt prepare'
+  const prepareCmd = getPrepareCmd(packageManager)
+  const runPrepare = isAutoRun || await promptUser(`Nuxt types and auto-imports should be regenerated after the update. Do you want to run \`${prepareCmd}\` now?`)
+  if (runPrepare) {
+    try {
+      showMessage(`Running \`${prepareCmd}\`...`)
+      execSync(prepareCmd, { stdio: 'inherit' })
+    } catch (error) {
+      console.error(`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?`)
   if (runPlaywrightUpdate) {
@@ -60,12 +76,15 @@ export async function specUpdate(autoRun = false) {
     }
   }
 
-  // 3) inform user
+  // 4) inform user
   showMessage('')
   showMessage('NUXT SPEC UPDATE COMPLETE', 2)
   if (!runUpdate) {
     showMessage(`Run \`${updateCmd}\` to update 'nuxt-spec'.`)
   }
+  if (!runPrepare) {
+    showMessage(`Run \`${prepareCmd}\` to regenerate the Nuxt types and auto-imports.`)
+  }
   if (!runPlaywrightUpdate) {
     showMessage(`Run \`${playwrightUpdateCmd}\` to update the Playwright browser runtimes for e2e tests.`)
   }

package/config/index.d.ts

@@ -15,7 +15,7 @@ type ExtendedUserConfig = UserConfig & {
  */
 type ProjectsConfig = boolean | {
   default?: boolean
-  node?: boolean
+  unit?: boolean
   nuxt?: boolean
   e2e?: boolean
   browser?: boolean

package/config/index.mjs

@@ -11,8 +11,12 @@ 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
+// 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 = {
@@ -46,11 +50,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',
         },
@@ -81,12 +85,26 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
           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
@@ -95,9 +113,9 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
           name: 'browser',
           include: ['test/browser/**/*.{test,spec}.ts'],
           environment: 'node',
-          // only chromium browser - add others manually if needed
+          // only chromium browser by default - add others manually if needed
           browser: {
-            provider: playwright(),
+            provider: playwright(playwrightConfig),
             enabled: true,
             headless: true,
             instances: [{

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": {
     "type": "git",
@@ -40,24 +40,26 @@
   "dependencies": {
     "@nuxt/eslint": "~1.17.0",
     "@nuxt/hints": "1.1.4",
-    "@nuxt/test-utils": "4.1.0",
+    "@nuxt/test-utils": "4.2.0",
     "@vitejs/plugin-vue": "~6.0.8",
-    "@vitest/browser": "4.1.10",
-    "@vitest/browser-playwright": "4.1.10",
-    "@vitest/ui": "4.1.10",
-    "@vue/test-utils": "2.4.11",
+    "@vitest/browser": "4.1.11",
+    "@vitest/browser-playwright": "4.1.11",
+    "@vitest/ui": "4.1.11",
+    "@vue/test-utils": "2.5.0",
     "elrh-cosca": "0.3.6",
     "fast-png": "~8.0.0",
-    "happy-dom": "~20.11.2",
+    "h3-next": "npm:h3@~2.0.1-rc.31",
+    "happy-dom": "~20.14.0",
     "nuxt": "4.5.2",
     "pixelmatch": "~7.2.0",
+    "playwright": "~1.62.1",
     "playwright-core": "~1.62.1",
     "typescript": "~6.0.3",
-    "vitest": "4.1.10",
+    "vitest": "4.1.11",
     "vitest-browser-vue": "2.1.0",
-    "vue": "~3.5.40",
-    "vue-router": "~5.2.0",
-    "vue-tsc": "~3.3.9"
+    "vue": "~3.5.42",
+    "vue-router": "~5.3.1",
+    "vue-tsc": "~3.3.11"
   },
   "scripts": {
     "analyze": "nuxt analyze",

package/utils/playwright.ts

@@ -0,0 +1,20 @@
+// Vitest setup file for the `e2e` project
+// allows connecting to an external Playwright instance,
+// if NUXT_SPEC_EXTERNAL_PLAYWRIGHT is set
+
+import { chromium, firefox, webkit } from 'playwright-core'
+import type { Browser, BrowserType } from 'playwright-core'
+
+const externalPlaywright = process.env.NUXT_SPEC_EXTERNAL_PLAYWRIGHT
+
+if (externalPlaywright) {
+  for (const browserType of [chromium, firefox, webkit] as BrowserType[]) {
+    console.log(`[Nuxt Spec - e2e] Using external Playwright instance at: ${externalPlaywright}`)
+    // @nuxt/test-utils always calls `playwright[type].launch()` with no way to opt into
+    // `connect()`, so the launch method is swapped for a connect against the WS endpoint
+    browserType.launch = (): Promise<Browser> => browserType.connect(externalPlaywright, {
+      // this allows reaching caller's localhost from within the external Playwright
+      exposeNetwork: '<loopback>',
+    })
+  }
+}