Installation & Configuration

Dependencies

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):

// 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:

// 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:

// 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:

// @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

# 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:

// nuxt.config.ts
export default defineNuxtConfig({
  typescript: {
    tsConfig: {
      include: [
        // relative to generated .nuxt/tsconfig.json
        '../test/other-nuxt-context/**/*',
      ],
    },
  },
})

3.0 KiB Raw Blame History