Initial commit

.claude/skills/nuxt-testing/references/setup-config.md

@@ -0,0 +1,147 @@
+# Installation & Configuration
+
+## Dependencies
+
+```bash
+pnpm add -D @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core
+```
+
+## Nuxt Config
+
+Add the test utils module for Vitest integration in DevTools (optional):
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '@nuxt/test-utils/module',
+  ],
+})
+```
+
+## Vitest Config (Project-Based Setup)
+
+Use Vitest projects for fine-grained control over which tests run in which environment:
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import { defineVitestProject } from '@nuxt/test-utils/config'
+
+export default defineConfig({
+  test: {
+    projects: [
+      {
+        test: {
+          name: 'unit',
+          include: ['test/unit/*.{test,spec}.ts'],
+          environment: 'node',
+        },
+      },
+      {
+        test: {
+          name: 'e2e',
+          include: ['test/e2e/*.{test,spec}.ts'],
+          environment: 'node',
+        },
+      },
+      await defineVitestProject({
+        test: {
+          name: 'nuxt',
+          include: ['test/nuxt/*.{test,spec}.ts'],
+          environment: 'nuxt',
+        },
+      }),
+    ],
+  },
+})
+```
+
+**Important:** Requires `"type": "module"` in `package.json`, or rename to `vitest.config.m{ts,js}`.
+
+## Alternative: Simple Setup
+
+If all tests should run in the Nuxt environment:
+
+```ts
+// vitest.config.ts
+import { defineVitestConfig } from '@nuxt/test-utils/config'
+
+export default defineVitestConfig({
+  test: {
+    environment: 'nuxt',
+    // environmentOptions: {
+    //   nuxt: {
+    //     domEnvironment: 'happy-dom', // 'happy-dom' (default) or 'jsdom'
+    //     overrides: {
+    //       // other Nuxt config
+    //     }
+    //   }
+    // }
+  },
+})
+```
+
+Opt out of the Nuxt environment per test file with a comment:
+
+```ts
+// @vitest-environment node
+import { test } from 'vitest'
+
+test('my test', () => {
+  // runs without Nuxt environment
+})
+```
+
+## Recommended Test Directory Structure
+
+```
+test/
+├── e2e/          # End-to-end tests (node environment)
+│   └── ssr.test.ts
+├── nuxt/         # Tests needing Nuxt runtime (nuxt environment)
+│   ├── components.test.ts
+│   └── composables.test.ts
+└── unit/         # Pure unit tests (node environment)
+    └── utils.test.ts
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+npx vitest
+
+# Run only unit tests
+npx vitest --project unit
+
+# Run only Nuxt tests
+npx vitest --project nuxt
+
+# Run tests in watch mode
+npx vitest --watch
+```
+
+## Environment Variables
+
+Use a `.env.test` file for test-specific environment variables.
+
+## TypeScript Support
+
+Test files in `test/nuxt/` and `tests/nuxt/` are automatically included in the Nuxt app TypeScript context, so they recognize `~/`, `@/`, `#imports` aliases and auto-imports.
+
+To add other directories to the Nuxt TypeScript context:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  typescript: {
+    tsConfig: {
+      include: [
+        // relative to generated .nuxt/tsconfig.json
+        '../test/other-nuxt-context/**/*',
+      ],
+    },
+  },
+})
+```