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

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:

// @vitest-environment nuxt

Environment Options

Configure in vitest.config.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
        },
      },
    },
  },
})