nuxt-spec 0.1.18 → 0.2.0-alpha.1

package/README.md

@@ -4,7 +4,7 @@
 
 **Nuxt Spec** (aka `nuxt-spec`) is a base layer for [Nuxt](https://nuxt.com/) applications incorporating together a couple of testing libraries and packages and providing some utility functions. I created this project in early 2025 because I was unable to find a convenient "one-dependency" way to start testing my Nuxt apps and I didn't want to repeat the same steps and maintain the same set of dependencies over and over. 
 
-While Nuxt itself does have a [dedicated module for testing](https://nuxt.com/docs/getting-started/testing), to remain as versatile as possible, it has to be combined with other packages (which can be different based on your choice). I am trying to overcome this by defining "the way". This is both the strength and the weakness of this project. You were warned.
+While Nuxt itself does have a [dedicated module for testing](https://nuxt.com/docs/getting-started/testing), to remain as versatile as possible, it has to be combined with other packages (which can be different based on your choice). I am trying to overcome this by defining "The Way". This is both the strength and the weakness of this project. You were warned.
 
 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.
 
@@ -16,6 +16,7 @@ The `nuxt-spec` package comes with a built-in CLI tool that can help you:
 - setup the dependency in your project
 - 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)
+- create demo test files in proposed file structure
 
 To use it, just run the CLI script in your terminal:
 
@@ -36,7 +37,7 @@ If you don't want to use the CLI tool, or you want to understand its flow better
 1) Add following dependency into your `package.json`:
 
 ```
-"nuxt-spec": "0.1.18"
+"nuxt-spec": "0.2.0-alpha.1"
 ```
 
 2) Add following section into your `nuxt.config.ts`:
@@ -77,15 +78,18 @@ export default loadVitestConfig({
 
 ```
 test/
+├── browser/
+│   └── vitest-browser.test.ts
 ├── e2e/
 │   └── nuxt-e2e.test.ts
+│   └── nuxt-visual.test.ts
 ├── nuxt/
 │   └── nuxt-unit.test.ts
 └── unit/
-    └── vitest.test.ts
+    └── vitest-unit.test.ts
 ```
 
-You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.1.18/test).
+You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.2.0-alpha.1/test).
 
 ### Install and execute
 
@@ -234,7 +238,8 @@ Or you can use the `vitest` command directly with all its parameters. See [Vites
 
 **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
+- [@vitest/browser](https://www.npmjs.com/package/@vitest/browser) as more advanced browser-native testing runner
+- [@vitest/ui](https://www.npmjs.com/package/@vitest/ui) as graphic UI above the Vitest test runner
 - [happy-dom](https://www.npmjs.com/package/happy-dom) as the headless browser runtime
 - [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
@@ -242,13 +247,13 @@ Or you can use the `vitest` command directly with all its parameters. See [Vites
 
 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)
+- solution for visual regression testing - (currently there is experimental custom solution)
 
-See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.1.18/CHANGELOG.md) for the latest updates and features.
+See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.1/CHANGELOG.md) for the latest updates and features.
 
 ## Configuration
 
-By default, `nuxt-spec` uses Vitest configuration defined in [`/config/index.mjs`](https://github.com/AloisSeckar/nuxt-spec/blob/v0.1.18/config/index.mjs). The configuration is based on [Nuxt team recommendations](https://nuxt.com/docs/4.x/getting-started/testing) and our best judgement.
+By default, `nuxt-spec` uses Vitest configuration defined in [`/config/index.mjs`](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.1/config/index.mjs). 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 (or scaffold via CLI tool) a file named `vitest.config.ts` in the root of your project with the following content:
 
@@ -271,16 +276,19 @@ export default loadVitestConfig({
   test: {
     // your custom config specific to Vitest here
   }
+  // by the nature of the Vitest config resolution,
+  // you may also pass ANY OTHER valid Vite configuration options here
 })
 ```
 
-By default, Nuxt Spec built-in configuration establishes 3 `projects` + one fallback:
+By default, Nuxt Spec built-in configuration establishes 4 `projects` + one fallback:
 - `unit` - for unit tests in `test/unit/**` - env is set to `node` 
 - `nuxt` - for Nuxt-related tests in `test/nuxt/**` - env is set to `nuxt` 
 - `e2e` - for end-to-end tests in `test/e2e/**` - env is set to `node` 
+- `browser` - for browser-mode tests in `test/browser/**` - env is set to `node` (this is effectively an alternative to `nuxt` relying on `@vitest/browser` instead of `@nuxt/test-utils`)
 - `default` - fallback for all other tests in `test/**` and/or `tests/**` directories - env is set to `node` 
 
-Vitest will then expects at least one test defined in either of those directories. The `test.projects` confing may be extended with others, but it cannot be easily removed due to nature of defu-merge process. If your project uses different configuration (i.e. your test reside in completely different path), you can pass `false` as a second parameter to `loadVitestConfig()` function to exclude `test.projects` key to be injected:
+Vitest will then expects at least one test defined in either of those directories. Any parts of the `test.projects` confing may be altered and user-defined values will be logically merged with the defaults. Also you may add new custom projects' definitions to fit your needs. If your project uses significantly different configuration (i.e. your tests reside in completely different path), you can pass `false` as a second parameter to `loadVitestConfig()` function to exclude default `test.projects` values from being injected completely:
 
 ```ts
 import { loadVitestConfig } from 'nuxt-spec/config'
@@ -292,6 +300,40 @@ export default loadVitestConfig({
 
 Alternatively, if you don't want to use any part of the `nuxt-spec` default configuration at all, you can override `vitest.config.ts` file completely and define your own [Vitest configuration](https://vitest.dev/config/) from scratch.
 
+## Utilities
+
+Nuxt Spec offers couple of utility functions that are exported via `nuxt-spec/utils` subpackage.
+
+You can use them in your test files as follows:
+
+```ts
+import { compareScrenshot, gotoPage, getDataHtml, getAPIResultHtml, } from 'nuxt-spec/utils'
+
+// accepts instance of NuxtPage (from @nuxt/test-utils)
+// takes a screenshot of current viewport and compares it with stored baseline
+// if screenshot doesn't exist, it will be created as baseline
+// if screenshots don't match, the method will cause Vitest test to fail
+await compareScrenshot(page, 'screenshot.png')
+
+// navigates to given URL and returns the instance of NuxtPage (from @nuxt/test-utils)
+const page: NuxtPage = await gotoPage('url')
+
+// accepts either a URL string or instance of NuxtPage (from @nuxt/test-utils) and a CSS selector
+// returns innerHTML of the element matching the selector
+const html: string = await getDataHtml('/', '#test') 
+const html: string = await getDataHtml(page, '#test')
+
+// accepts either a URL string or instance of NuxtPage (from @nuxt/test-utils)
+// css selector for element that triggers API call when clicked (i.e. button)
+// fragment of API endpoint URL that should be called (to test the response)
+// css selector for element where the API response should be rendered (i.e. div)
+// returns innerHTML of the element matching the result selector after the API call is made by Playwright runner
+const html: string = await getAPIResultHtml('/', '#api-fetch', 'jsonplaceholder.typicode.com/posts', '#api-result')
+const html: string = await getAPIResultHtml(page, '#api-fetch', 'jsonplaceholder.typicode.com/posts', '#api-result')
+```
+
+For detailed description, see [utils.d.ts](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.1/utils/index.d.ts).
+
 ## Contact
 
 Use GitHub issues to report bugs or suggest improvements. I will be more than happy to address them.

package/app/app.vue

@@ -4,6 +4,7 @@
     <div>
       Test-pack layer for <a href="https://nuxt.com/">Nuxt</a> applications
     </div>
-    <NuxtSpecTestComponent text="Test Component" />
+    <NuxtSpecTestComponent id="test" text="Test Component" />
+    <NuxtSpecApiTestComponent />
   </div>
 </template>

package/app/components/NuxtSpecApiTestComponent.vue

@@ -0,0 +1,24 @@
+<template>
+  <div>
+    <h2>API Test</h2>
+    <button id="api-fetch" @click="fetchData">
+      Fetch Data
+    </button>
+    <div id="api-result">
+      {{ data }}
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const data = ref('')
+const fetchData = async () => {
+  try {
+    data.value = await $fetch('https://jsonplaceholder.typicode.com/posts/1')
+    console.debug('Fetched data:', data.value)
+  } catch (error) {
+    data.value = 'Error fetching data'
+    console.error('API fetch error:', error)
+  }
+}
+</script>

package/bin/setup.js

@@ -37,7 +37,7 @@ export async function specSetup(autoRun = false) {
   // add nuxt-spec
   try {
     await updateJsonFile('package.json', 'dependencies', {
-      'nuxt-spec': '0.1.18',
+      'nuxt-spec': '0.2.0-alpha.1',
     }, isAutoRun, 'This will add \'nuxt-spec\' dependency to your \'package.json\'. Continue?')
   } catch (error) {
     console.error('Error adding \'nuxt-spec\' dependency:\n', error.message)
@@ -107,7 +107,7 @@ export async function specSetup(autoRun = false) {
       if (pathExists('.npmrc')) {
         await updateTextFile('.npmrc', ['shamefully-hoist=true'], isAutoRun, 'This will adjust \'.npmrc\' file in your project. Continue?')
       } else {
-        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.1.18/.npmrc',
+        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.1/.npmrc',
           '.npmrc', isAutoRun, 'This will add \'.npmrc\' file for your project. Continue?')
       }
     } catch (error) {
@@ -117,7 +117,7 @@ export async function specSetup(autoRun = false) {
 
   // 4) create vitest.config.ts
   try {
-    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.1.18/config/vitest.config.ts.template',
+    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.1/config/vitest.config.ts.template',
       'vitest.config.ts', isAutoRun, 'This will create a new \'vitest.config.ts\' file for your project. Continue?')
   } catch (error) {
     console.error('Error setting up \'vitest.config.ts\':\n', error.message)
@@ -155,22 +155,34 @@ export async function specSetup(autoRun = false) {
   const createSampleTests = isAutoRun || await promptUser('Do you want to create sample tests in \'/test\' folder?')
   if (createSampleTests) {
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.1.18/test/e2e/nuxt-e2e.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.1/test/browser/vitest-browser.test.ts',
+        'test/browser/vitest-browser.test.ts', true)
+    } catch (error) {
+      console.error('Error setting up \'vitest-browser.test.ts\':\n', error.message)
+    }
+    try {
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.1/test/e2e/nuxt-e2e.test.ts',
         'test/e2e/nuxt-e2e.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'nuxt-e2e.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.1.18/test/nuxt/nuxt-unit.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.1/test/e2e/nuxt-visual.test.ts',
+        'test/e2e/nuxt-visual.test.ts', true)
+    } catch (error) {
+      console.error('Error setting up \'nuxt-visual.test.ts\':\n', error.message)
+    }
+    try {
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.1/test/nuxt/nuxt-unit.test.ts',
         'test/nuxt/nuxt-unit.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'nuxt-unit.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.1.18/test/unit/vitest.test.ts',
-        'test/unit/vitest.test.ts', true)
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.1/test/unit/vitest-unit.test.ts',
+        'test/unit/vitest-unit.test.ts', true)
     } catch (error) {
-      console.error('Error setting up \'vitest.test.ts\':\n', error.message)
+      console.error('Error setting up \'vitest-unit.test.ts\':\n', error.message)
     }
   }
 

package/config/index.mjs

@@ -2,9 +2,11 @@
 // 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 { defu } from 'defu'
+import { mergeConfig } from './merge' // 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'
 
 export async function loadVitestConfig(userVitestConfig, projects = true) {
   const baseConfig = {
@@ -17,19 +19,19 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
       {
         test: {
           name: 'default',
-          include: ['{test,tests}/**/*.{test,spec}.ts', '!test/{nuxt,e2e,unit}/**'],
+          include: ['{test,tests}/**/*.{test,spec}.ts', '!test/{browser,e2e,nuxt,unit}/**'],
           environment: 'node',
         },
       },
-      // proposed setup for unit and e2e tests
+      // proposed setup for Unit tests
       {
         test: {
           name: 'node',
-          include: ['test/{e2e,unit}/**/*.{test,spec}.ts'],
+          include: ['test/unit/**/*.{test,spec}.ts'],
           environment: 'node',
         },
       },
-      // proposed setup for Nuxt
+      // proposed setup for Nuxt component tests
       await defineVitestProject({
         test: {
           name: 'nuxt',
@@ -37,8 +39,35 @@ export async function loadVitestConfig(userVitestConfig, projects = true) {
           environment: 'nuxt',
         },
       }),
+      // proposed setup for classic E2E tests (node-based, using @nuxt/test-utils)
+      {
+        test: {
+          name: 'e2e',
+          include: ['test/e2e/**/*.{test,spec}.ts'],
+          environment: 'node',
+        },
+      },
+      // proposed setup for browser component tests (with Playwright runner)
+      {
+        // vue plugin is required for proper imports resolution
+        plugins: [vue()],
+        test: {
+          name: 'browser',
+          include: ['test/browser/**/*.{test,spec}.ts'],
+          environment: 'node',
+          browser: {
+            provider: playwright(),
+            enabled: true,
+            headless: true,
+            instances: [{
+              browser: 'chromium',
+              viewport: { width: 1280, height: 720 },
+            }],
+          },
+        },
+      },
     ]
   }
 
-  return defu(userVitestConfig, defineConfig(baseConfig))
+  return mergeConfig(userVitestConfig, defineConfig(baseConfig))
 }

package/config/merge.ts

@@ -0,0 +1,40 @@
+// 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 into OVERRIDE insteead of merging with nuxt-spec defaults
+
+import { createDefu } from 'defu'
+
+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 => o.name === defaultProject.name)
+      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 => d.name === override.name)) {
+        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/nuxt.config.ts

@@ -4,7 +4,7 @@ export default defineNuxtConfig({
     '@nuxt/test-utils/module',
   ],
 
-  compatibilityDate: '2025-12-14',
+  compatibilityDate: '2026-02-22',
 
   eslint: {
     config: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.1.18",
+  "version": "0.2.0-alpha.1",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": "github:AloisSeckar/nuxt-spec",
   "license": "MIT",
@@ -15,6 +15,11 @@
       "types": "./config/index.d.ts",
       "import": "./config/index.mjs",
       "default": "./config/index.mjs"
+    },
+    "./utils": {
+      "types": "./utils/index.d.ts",
+      "import": "./utils/index.ts",
+      "default": "./utils/index.ts"
     }
   },
   "files": [
@@ -24,18 +29,22 @@
     "public"
   ],
   "dependencies": {
-    "@nuxt/eslint": "1.14.0",
+    "@nuxt/eslint": "1.15.1",
     "@nuxt/test-utils": "4.0.0",
+    "@vitejs/plugin-vue": "6.0.4",
     "@vitest/browser": "4.0.18",
+    "@vitest/browser-playwright": "4.0.18",
+    "@vitest/ui": "4.0.18",
     "@vue/test-utils": "2.4.6",
     "elrh-cosca": "0.3.5",
-    "happy-dom": "20.5.1",
+    "happy-dom": "20.7.0",
     "nuxt": "4.3.1",
     "playwright-core": "1.58.2",
     "typescript": "5.9.3",
     "vitest": "4.0.18",
-    "vue": "3.5.27",
-    "vue-router": "5.0.2"
+    "vitest-browser-vue": "2.0.2",
+    "vue": "3.5.28",
+    "vue-router": "5.0.3"
   },
   "scripts": {
     "analyze": "nuxt analyze",