# 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/**/*',
      ],
    },
  },
})
```