nuxt-spec 0.0.4 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+Overview of the newest features in Nuxt Spec.
+
+## 0.1.1
+
+**2025-08-09**
+
+- feat: CLI tool for scaffolding `vitest.config.ts` and test-related scripts in `package.json`
+- docs: added `CHANGELOG.md` and fixed link to `playwright-core`
+
+## 0.1.0
+
+**2025-08-08**
+
+- initial release [v0.1.0](https://github.com/AloisSeckar/nuxt-spec/releases/tag/v0.1.0)
+- key features:
+  - Nuxt base layer for testing
+  - Nuxt v4 and Vitest v4 compatibility
+  - Integrated `vitest`, `@vitest/browser`, `happy-dom`, `playwright-core`, `@vue/test-utils`, `@nuxt/test-utils`
+  - Support for custom configuration via `loadVitestConfig` function in `vitest.config.ts`

package/README.md

@@ -8,14 +8,13 @@ While Nuxt itself does have a [dedicated module for testing](https://nuxt.com/do
 
 The most important client of `nuxt-spec` is my [Nuxt Ignis](https://github.com/AloisSeckar/nuxt-ignis) template starter that adds up even more ready-to-use cool stuff for your future awesome Nuxt websites.
 
-
 ## How to use
 
 Aside from being "forked" and used as you seem fit, `nuxt-spec` is also available as an [NPM package](https://www.npmjs.com/package/nuxt-spec) that can be referenced as a single-import with all the features incoming.
 
 1) Add following dependency into your `package.json`:
 ```
-"nuxt-spec": "0.0.4"
+"nuxt-spec": "0.1.1"
 ```
 
 2) Add following section into your `nuxt.config.ts`:
@@ -33,26 +32,68 @@ strict-peer-dependencies=false
 
 4) If you're prompoted, run `npm exec playwright-core install` to download and locally install headless browser runtimes.
 
-
 **DONE.** You are just `npm install` and `npm run dev` away from testing your Nuxt projects!
 
+### Optional setup
+
+The `nuxt-spec` package comes with a CLI tool that can help you:
+- scaffold the default `vitest.config.ts` (see [configuration](#configuration) section)
+- add a few test-related script shorthands into your `package.json` (see [running tests](#running-tests) section)
+
+To use it, just run the following command in your terminal after you installed `nuxt-spec` package (files must be available in your `node_modules` folder):
+
+```bash
+npx nuxt-spec-cli
+```
+
+You will be prompted for each action which allows you to choose only one action to run and skip the other.
+
+### Running tests
+
+Once installed, Vitest automatically discovers all `*.test.ts` and `*.spec.ts` files in project and will run them.
+
+It is recommended to have following three commands `package.json` file in `"scripts"` section in order to run tests easilly:
+- `test: vitest run` - runs once and ends
+- `test-u: vitest run -u` - runs once and updates snapshots
+- `test-i: vitest` - runs and waits in HMR mode for test file changes
+
+Then you can call in terminal in root of your project: 
+
+`npm run test` | `npm run test-u` | `npm run test-i`
 
 ## Overview
 
-**Nuxt T(est)** currently contains:
-- [vitest](https://www.npmjs.com/package/vitest) as the fundamental testing framework
+**Nuxt Spec** currently contains:
+- [vitest](https://www.npmjs.com/package/vitest) **v4** as the fundamental testing framework
+- [@vitest/browser](https://www.npmjs.com/package/@vitest/browser) as the experimental browser runner
 - [happy-dom](https://www.npmjs.com/package/happy-dom) as the headless browser runtime
-- [playwright-core](https://www.npmjs.com/package/vitest) as the headless browser testing framework
+- [playwright-core](https://www.npmjs.com/package/playwright-core) as the headless browser testing framework
 - [@vue/test-utils](https://www.npmjs.com/package/@vue/test-utils) for testing Vue stuff
 - [@nuxt/test-utils](https://www.npmjs.com/package/@nuxt/test-utils) for testing Nuxt stuff
 
-The suite provides two (p)npm commands, that can be run out-of-the-box in extending Nuxt projects:
-- `test` - equal to `vitest run` (runs once and ends)
-- `test-i` - equal to `vitest` (runs and waits in HMR for test changes)
+Planned future development:
+- reason about (not) using Vitest browser mode (or make it optional)
+- solution for visual testing - either [backstopjs](https://www.npmjs.com/package/backstopjs) or Vitest's native (currently experimental)
+
+See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/main/CHANGELOG.md) for the latest updates and features.
+
+## Configuration
+
+By default, `nuxt-spec` uses Vitest configuration defined in [`/utils/vitest-config.ts`](https://github.com/AloisSeckar/nuxt-spec/blob/main/utils/vitest-config.ts). The configuration is based on [Nuxt team recommendations](https://nuxt.com/docs/4.x/getting-started/testing) and our best judgement.
+
+To add/override your custom config, you can create a file named `vitest.config.ts` in the root of your project with the following content:
+
+```ts
+import { loadVitestConfig } from './app/utils/vitest-config'
+
+export default loadVitestConfig({
+  // your custom config here
+})
+```
 
-Planned future content:
-- [backstopjs](https://www.npmjs.com/package/backstopjs) as the solution for visual testing
+And pass whatever you want as a parameter object. It will be defu-merged with the defaults (custom config takes precedence).
 
+Alternatively, if you don't want to use any part of the `nuxt-spec` default configuration, you can override `vitest.config.ts` file completely and define your own [Vitest configuration](https://vitest.dev/config/) from scratch.
 
 ## Contact
 

package/app/app.vue

@@ -0,0 +1,9 @@
+<template>
+  <div>
+    <h1>Nuxt Spec</h1>
+    <div>
+      Test-pack layer for <a href="https://nuxt.com/">Nuxt</a> applications
+    </div>
+    <NuxtTestComponent text="Test Component" />
+  </div>
+</template>

package/{components → app/components}/NuxtTestComponent.vue

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

package/app/utils/vitest-config.ts

@@ -0,0 +1,31 @@
+// this is the default Vitest config object
+// based on https://nuxt.com/docs/4.x/getting-started/testing#setup
+
+import { defu } from 'defu'
+import { defineConfig } from 'vitest/config'
+import { defineVitestProject } from '@nuxt/test-utils/config'
+
+// @ts-expect-error no-implicit-any
+// TODO set proper type for the object
+export async function loadVitestConfig(userVitestConfig) {
+  return defu(userVitestConfig, defineConfig({
+    test: {
+      projects: [
+        {
+          test: {
+            name: 'node',
+            include: ['test/{e2e,unit}/*.{test,spec}.ts'],
+            environment: 'node',
+          },
+        },
+        await defineVitestProject({
+          test: {
+            name: 'nuxt',
+            include: ['test/nuxt/*.{test,spec}.ts'],
+            environment: 'nuxt',
+          },
+        }),
+      ],
+    },
+  }))
+}

package/bin/spec-setup.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+// CLI tool to scaffold default `vitest.config.ts` file
+// and to add test-related commands in `package.json`
+// usage: `npx spec-setup.js` in target folder
+
+import { createFileFromTemplate } from './utils/create-file.js'
+import { updatePackageJsonScripts } from './utils/modify-scripts.js'
+
+async function main() {
+  // 1) create vitest.config.ts
+  await createFileFromTemplate('../vitest.config.ts', 'vitest.config.ts')
+
+  // 2) modify scripts in package.json
+  await updatePackageJsonScripts({
+    'test': 'vitest run',
+    'test-u': 'vitest run -u',
+    'test-i': 'vitest',
+  })
+}
+
+main().catch((err) => {
+  console.error('Error:', err)
+  process.exit(1)
+})

package/bin/utils/create-file.js

@@ -0,0 +1,37 @@
+import path from 'path'
+import { existsSync, copyFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import { promptUser } from './prompt-user.js'
+
+export async function createFileFromTemplate(templateFile, targetFile) {
+  const shouldCreate = await promptUser(
+    `This will create default 'vitest.config.ts' file. Continue?`,
+  )
+  if (shouldCreate) {
+    const __filename = fileURLToPath(import.meta.url)
+    const __dirname = path.dirname(__filename)
+
+    const templatePath = path.resolve(__dirname, `../${templateFile}`)
+    const targetPath = path.resolve(process.cwd(), `../${targetFile}`)
+
+    if (!existsSync(templatePath)) {
+      console.error(`Template file not found at ${templatePath}`)
+      process.exit(1)
+    }
+
+    if (existsSync(targetPath)) {
+      const shouldOverwrite = await promptUser(
+        `File 'vitest.config.ts' already exists. Overwrite?`,
+      )
+      if (!shouldOverwrite) {
+        console.log('Aborted.')
+        process.exit(0)
+      }
+    }
+
+    copyFileSync(templatePath, targetPath)
+    console.log(`Default 'vitest.config.ts' successfully created.`)
+  } else {
+    console.log(`Creation of 'vitest.config.ts' skipped.`)
+  }
+}

package/bin/utils/modify-scripts.js

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import path from 'path'
+import { promptUser } from './prompt-user.js'
+
+export async function updatePackageJsonScripts(scriptsToAdd) {
+  const shouldUpdate = await promptUser(
+    `This will update scripts section of 'package.json' file. Continue?`,
+  )
+  if (shouldUpdate) {
+    const packageJsonPath = path.resolve(process.cwd(), 'package.json')
+
+    if (!existsSync(packageJsonPath)) {
+      console.warn(`No 'package.json' found in project root — skipping script updates.`)
+      return
+    }
+
+    const pkgRaw = readFileSync(packageJsonPath, 'utf8')
+    let pkg
+    try {
+      pkg = JSON.parse(pkgRaw)
+    } catch {
+      console.error(`Could not parse 'package.json' — skipping script updates.`)
+      return
+    }
+
+    pkg.scripts = pkg.scripts || {}
+
+    let modified = false
+
+    for (const [name, cmd] of Object.entries(scriptsToAdd)) {
+      if (pkg.scripts[name] !== cmd) {
+        pkg.scripts[name] = cmd
+        modified = true
+      }
+    }
+
+    if (modified) {
+      writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8')
+      console.log(`Scripts section of 'package.json' updated.`)
+    } else {
+      console.log(`Scripts section of 'package.json' already up to date.`)
+    }
+  } else {
+    console.log(`Adding scripts to 'package.json' skipped.`)
+  }
+}

package/bin/utils/prompt-user.js

@@ -0,0 +1,15 @@
+import readline from 'readline'
+
+export async function promptUser(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  })
+
+  return new Promise((resolve) => {
+    rl.question(question + ' (y/N): ', (answer) => {
+      rl.close()
+      resolve(/^y(es)?$/i.test(answer.trim()))
+    })
+  })
+}

package/eslint.config.mjs

@@ -5,9 +5,6 @@ import withNuxt from './.nuxt/eslint.config.mjs'
 
 export default withNuxt([
 
-  // files to be processed (JS/TS + Vue components)
-  { files: ['**/*.js', '**/*.ts', '**/*.vue'] },
-
   // `rules` section can follow, where you can change default eslint behaviour if needed
   // you can adjust or even turn off some rules if you cannot or don't want to satisfy them
   {

package/nuxt.config.ts

@@ -4,7 +4,7 @@ export default defineNuxtConfig({
     '@nuxt/test-utils/module',
   ],
 
-  compatibilityDate: '2025-01-26',
+  compatibilityDate: '2025-08-08',
 
   eslint: {
     config: {

package/package.json

@@ -1,33 +1,37 @@
-{
-  "name": "nuxt-spec",
-  "version": "0.0.4",
-  "description": "Test-pack layer for Nuxt Applications",
-  "repository": "github:AloisSeckar/nuxt-spec",
-  "license": "MIT",
-  "type": "module",
-  "main": "./nuxt.config.ts",
-  "scripts": {
-    "analyze": "nuxt analyze",
-    "eslint": "eslint .",
-    "build": "nuxt build",
-    "dev": "nuxt dev",
-    "generate": "nuxt generate",
-    "preview": "nuxt preview",
-    "start": "nuxt start",
-    "test": "vitest run",
-    "test-i": "vitest"
-  },
-  "dependencies": {
-    "@nuxt/test-utils": "3.15.4",
-    "@vue/test-utils": "2.4.6",
-    "happy-dom": "16.8.1",
-    "playwright-core": "1.50.1",
-    "vitest": "3.0.5"
-  },
-  "devDependencies": {
-    "@nuxt/eslint": "0.7.6",
-    "nuxt": "3.15.4",
-    "typescript": "latest"
-  },
-  "packageManager": "pnpm@9.15.5"
-}
+{
+  "name": "nuxt-spec",
+  "version": "0.1.1",
+  "description": "Test-pack layer for Nuxt Applications",
+  "repository": "github:AloisSeckar/nuxt-spec",
+  "license": "MIT",
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "bin": {
+    "spec-setup": "./bin/spec-setup.js"
+  },
+  "dependencies": {
+    "@nuxt/test-utils": "3.19.2",
+    "@vue/test-utils": "2.4.6",
+    "happy-dom": "18.0.1",
+    "playwright-core": "1.54.2",
+    "vitest": "4.0.0-beta.7",
+    "@vitest/browser": "4.0.0-beta.7"
+  },
+  "devDependencies": {
+    "@nuxt/eslint": "1.8.0",
+    "nuxt": "4.0.3",
+    "typescript": "5.9.2"
+  },
+  "scripts": {
+    "analyze": "nuxt analyze",
+    "eslint": "eslint .",
+    "build": "nuxt build",
+    "dev": "nuxt dev",
+    "generate": "nuxt generate",
+    "preview": "nuxt preview",
+    "start": "nuxt start",
+    "test": "vitest run",
+    "test-u": "vitest run -u",
+    "test-i": "vitest"
+  }
+}

package/test/{nuxt-e2e.test.ts → e2e/nuxt-e2e.test.ts}

@@ -4,18 +4,18 @@ import { describe, expect, test } from 'vitest'
 describe('NuxtTestComponent E2E test', async () => {
   // setup app.vue in headless browser
   await setup()
-  
+
   test('component renders in browser', async () => {
     // fetch for the rendered value
     const html = await $fetch('/')
-    expect(html).toContain('nuxt-spec')
+    expect(html).toContain('Test Component')
   })
 
   test('with playwright', async () => {
     // render page in headless browser
     const page = await createPage()
     await page.goto(url('/'), { waitUntil: 'hydration' })
-    const hasText = await page.getByText('nuxt-spec').isVisible()
+    const hasText = await page.getByText('Test Component').isVisible()
     expect(hasText).toBeTruthy()
   })
 })

package/test/{nuxt-unit.test.ts → nuxt/nuxt-unit.test.ts}

@@ -1,9 +1,7 @@
 import { describe, test, expect } from 'vitest'
 import { mount } from '@vue/test-utils'
 import { mountSuspended } from '@nuxt/test-utils/runtime'
-import NuxtTestComponent from '../components/NuxtTestComponent.vue'
-
-// mockNuxtImport - macro for mimicking external functionality for unit tests
+import NuxtTestComponent from '../../app/components/NuxtTestComponent.vue'
 
 const text = 'custom-text'
 

package/vitest.config.ts

@@ -0,0 +1,8 @@
+// custom Vitest configuration wrapper that allows custom user config
+// to be merged with defaults provided by nuxt-spec package
+
+import { loadVitestConfig } from './app/utils/vitest-config'
+
+export default loadVitestConfig({
+  // custom config here
+})

package/app.vue

@@ -1,9 +0,0 @@
-<template>
-  <div>
-    <h1>Nuxt T(est)</h1>
-    <div>
-      Test-pack layer for <a href="https://nuxt.com/">Nuxt</a> Applications
-    </div>
-    <NuxtTestComponent />
-  </div>
-</template>

package/vitest.config.mts

@@ -1,8 +0,0 @@
-import { defineVitestConfig } from '@nuxt/test-utils/config'
-
-export default defineVitestConfig({
-  test: {
-    environment: 'nuxt',
-    setupFiles: ['./utils/vitest-utils.ts'],
-  },
-})