Nuxt Test Utils入門｜v4対応セットアップからUnit Test・E2Eテストまで

npm install --save-dev @nuxt/test-utils vitest @vue/test-utils happy-dom playwright-core

// vitest.config.ts
import { defineVitestConfig } from '@nuxt/test-utils/config'

export default defineVitestConfig({
  test: {
    environment: 'nuxt',
    environmentOptions: {
      nuxt: {
        domEnvironment: 'happy-dom',
      },
    },
  },
})

// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { defineVitestProject } from '@nuxt/test-utils/config'

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'unit',
          include: ['tests/unit/**/*.{test,spec}.ts'],
          environment: 'node',
        },
      },
      await defineVitestProject({
        test: {
          name: 'nuxt',
          include: ['tests/nuxt/**/*.{test,spec}.ts'],
          environment: 'nuxt',
        },
      }),
      {
        test: {
          name: 'e2e',
          include: ['tests/e2e/**/*.{test,spec}.ts'],
          environment: 'node',
        },
      },
    ],
  },
})

my-component.nuxt.test.ts
my-component.nuxt.spec.ts

// @vitest-environment nuxt
import { describe, it, expect } from 'vitest'

export default defineVitestConfig({
  test: {
    environment: 'nuxt',
  },
})

project-root/
├── components/
│   └── UserProfile.vue
├── composables/
│   └── useUser.ts
├── server/
│   └── api/
│       └── users.ts
├── tests/
│   ├── unit/          # Nuxt環境不要のロジックテスト
│   │   └── utils.test.ts
│   ├── nuxt/          # Nuxt環境が必要なテスト
│   │   ├── UserProfile.nuxt.test.ts
│   │   └── useUser.nuxt.test.ts
│   └── e2e/           # ブラウザ・サーバー連携テスト
│       └── navigation.test.ts
├── vitest.config.ts
└── package.json

import { mountSuspended } from '@nuxt/test-utils/runtime'
import { UserProfile } from '#components'

describe('UserProfile', () => {
  it('ユーザー名が表示される', async () => {
    const wrapper = await mountSuspended(UserProfile, {
      props: { userId: '123' },
      route: '/users/123',
    })
    expect(wrapper.text()).toContain('テストユーザー')
  })
})

import { renderSuspended } from '@nuxt/test-utils/runtime'
import { UserProfile } from '#components'
import { screen } from '@testing-library/vue'

describe('UserProfile', () => {
  it('アクセシブルな要素が存在する', async () => {
    await renderSuspended(UserProfile, {
      props: { userId: '123' },
    })
    expect(screen.getByRole('heading')).toBeDefined()
  })
})

import { mockNuxtImport } from '@nuxt/test-utils/runtime'

// useRouteをモック
mockNuxtImport('useRoute', () => {
  return () => ({
    params: { id: '456' },
    path: '/items/456',
  })
})

import { mockNuxtImport } from '@nuxt/test-utils/runtime'

const { useRouteMock } = vi.hoisted(() => ({
  useRouteMock: vi.fn(() => ({
    params: { id: '1' },
  })),
}))

mockNuxtImport('useRoute', () => useRouteMock)

describe('ItemPage', () => {
  it('IDが1の場合', async () => {
    useRouteMock.mockReturnValue({ params: { id: '1' } })
    // ...テストコード
  })

  it('IDが2の場合', async () => {
    useRouteMock.mockReturnValue({ params: { id: '2' } })
    // ...テストコード
  })
})

// v4.0.0: 元の実装を利用した部分モック
mockNuxtImport('useAuth', (original) => {
  return () => ({
    ...original(),
    isLoggedIn: true,
  })
})

import { mockComponent } from '@nuxt/test-utils/runtime'

// インラインでスタブを定義
mockComponent('HeavyChart', {
  props: { data: Array },
  setup(props) {
    return () => h('div', `Chart: ${props.data.length} items`)
  },
})

// SFCファイルにリダイレクト
mockComponent('HeavyChart', () => import('./stubs/MockChart.vue'))

mockComponent('Counter', async () => {
  const { ref, h } = await import('vue')
  return defineComponent({
    setup() {
      const count = ref(0)
      return () => h('span', count.value)
    },
  })
})

import { registerEndpoint } from '@nuxt/test-utils/runtime'

// GETリクエストのモック
registerEndpoint('/api/users/123', () => ({
  id: '123',
  name: 'テストユーザー',
  email: 'test@example.com',
}))

// POSTリクエストのモック
registerEndpoint('/api/users', {
  method: 'POST',
  handler: () => ({ id: '789', created: true }),
})

import { describe, it, expect } from 'vitest'
import { setup, $fetch } from '@nuxt/test-utils/e2e'

describe('トップページ', async () => {
  await setup({
    rootDir: '.',
    server: true,
    build: true,
    setupTimeout: 120000,
  })

  it('HTMLが正しくレンダリングされる', async () => {
    const html = await $fetch('/')
    expect(html).toContain('Welcome')
  })
})

import { setup, $fetch } from '@nuxt/test-utils/e2e'

describe('APIエンドポイント', async () => {
  await setup({ server: true })

  it('/api/healthが正常なレスポンスを返す', async () => {
    const data = await $fetch('/api/health')
    expect(data).toEqual({ status: 'ok' })
  })

  it('トップページに見出しが含まれる', async () => {
    const html = await $fetch('/')
    expect(html).toContain('<h1>')
  })
})

import { setup, createPage, url } from '@nuxt/test-utils/e2e'

describe('ナビゲーション', async () => {
  await setup({ browser: true })

  it('リンクをクリックして遷移する', async () => {
    const page = await createPage('/')
    await page.click('a[href="/about"]')
    await page.waitForURL(url('/about'))
    const heading = await page.textContent('h1')
    expect(heading).toBe('About')
  })
})

// playwright.config.ts
import { fileURLToPath } from 'node:url'
import { defineConfig } from '@playwright/test'
import type { ConfigOptions } from '@nuxt/test-utils/playwright'

export default defineConfig<ConfigOptions>({
  use: {
    nuxt: {
      rootDir: fileURLToPath(new URL('.', import.meta.url)),
    },
  },
})

// tests/e2e/home.spec.ts
import { expect, test } from '@nuxt/test-utils/playwright'

test('トップページの表示', async ({ page, goto }) => {
  await goto('/', { waitUntil: 'hydration' })
  await expect(page.getByRole('heading')).toHaveText('Welcome')
})

tests/
├── nuxt/                  # @nuxt/test-utils/runtime を使用
│   └── UserProfile.nuxt.test.ts
└── e2e/                   # @nuxt/test-utils/e2e を使用
    └── navigation.test.ts

{
  "devDependencies": {
    "@nuxt/test-utils": "^4.0.0",
    "vitest": "^4.0.2",
    "@vitest/coverage-v8": "^4.0.0",
    "happy-dom": ">=20.0.11",
    "@testing-library/vue": "^8.0.1"
  }
}

// NG: v4ではエラー
describe('MyTest', () => {
  const route = useRoute() // Nuxt環境がまだ初期化されていない
})

// OK: beforeAllまたはテスト関数内で呼び出す
describe('MyTest', () => {
  let route: ReturnType<typeof useRoute>

  beforeAll(() => {
    route = useRoute()
  })

  it('ルート情報を取得できる', () => {
    expect(route.path).toBe('/')
  })
})

// NG: v4ではsomeOtherExportがモックされていないためエラー
vi.mock('~/composables/useAuth', () => ({
  useAuth: () => ({ isLoggedIn: true }),
  // someOtherExportが定義されていない
}))

// OK: importOriginalで元のエクスポートを維持
vi.mock('~/composables/useAuth', async (importOriginal) => ({
  ...(await importOriginal()),
  useAuth: () => ({ isLoggedIn: true }),
}))

// vitest.config.ts
export default defineVitestConfig({
  test: {
    environment: 'nuxt',
    environmentOptions: {
      nuxt: {
        mock: {
          intersectionObserver: true,  // デフォルト: 有効
          indexedDb: false,            // デフォルト: 無効
        },
      },
    },
  },
})

# .env.test
API_BASE_URL=http://localhost:3000
AUTH_SECRET=test-secret-key