Initial commit

.claude/skills/nuxt-testing/references/unit-nuxt-environment.md

@@ -0,0 +1,49 @@
+# Nuxt Runtime Environment
+
+## Overview
+
+The Nuxt test environment initializes a global Nuxt app before tests run, including plugins and `app.vue`. This gives tests access to auto-imports, composables, and injections.
+
+Tests run in `happy-dom` (default) or `jsdom`. Be careful not to mutate global state, or reset it afterwards.
+
+## Environment Separation
+
+- **`test/unit/`** — Node environment, fast, no Nuxt runtime. For pure logic, utilities, helpers.
+- **`test/nuxt/`** — Nuxt environment, has access to auto-imports, composables, plugins. For components and composables that depend on Nuxt.
+- **`test/e2e/`** — Node environment, launches a full Nuxt server. For end-to-end testing.
+
+**Important:** `@nuxt/test-utils/runtime` and `@nuxt/test-utils/e2e` cannot be used in the same file — they need different environments.
+
+## Naming Convention for Mixed Setups
+
+If using the simple (non-project) config, separate by file extension:
+
+- `app.nuxt.spec.ts` — runs in Nuxt environment (uses `@nuxt/test-utils/runtime`)
+- `app.e2e.spec.ts` — runs in Node environment (uses `@nuxt/test-utils/e2e`)
+
+Or use per-file environment comments:
+
+```ts
+// @vitest-environment nuxt
+```
+
+## Environment Options
+
+Configure in `vitest.config.ts`:
+
+```ts
+import { defineVitestConfig } from '@nuxt/test-utils/config'
+
+export default defineVitestConfig({
+  test: {
+    environmentOptions: {
+      nuxt: {
+        domEnvironment: 'happy-dom', // or 'jsdom'
+        overrides: {
+          // Nuxt config overrides for testing
+        },
+      },
+    },
+  },
+})
+```