Nuxt Test Utils

The project uses @nuxt/eslint-config/flat to generate a Nuxt-compatible ESLint configuration via the createConfigForNuxt function. This allows you to enable specific Nuxt features and define which directories should be linted.

Configuration Options

features An object to enable or disable specific ESLint feature sets:

• tooling: Enables tooling-related rules.
• stylistic: Enables stylistic rules.

dirs An object defining the directories to be included in the linting process. The src key accepts an array of paths.

.append() After calling createConfigForNuxt, you can use the .append() method to add custom ESLint rules to the generated configuration.

import { createConfigForNuxt } from '@nuxt/eslint-config/flat'

export default createConfigForNuxt({
  features: {
    tooling: true,
    stylistic: true,
  },
  dirs: {
    src: ['./examples/app-vitest'],
  },
}).append({
  rules: {
    'vue/multi-word-component-names': 'off',
  },
})

To enable mocking of Nuxt imports (such as useRuntimeConfig, useAppConfig, etc.) in your tests, use the setupImportMocking function. This function works as a macro that transforms mockNuxtImport() calls into vi.mock() calls, allowing you to intercept and provide custom implementations for Nuxt-specific auto-imports.

When called, it performs the following setup:

• Hooks into the Nuxt lifecycle to capture component and import contexts.
• Configures Vite to use a specialized mock plugin.
• Adjusts Nuxt's ignore patterns to ensure .spec. and .test. files are processed.
• Filters out test files from being registered as actual Nuxt plugins during app:resolve.
• Removes setInterval from imports:sources to prevent mocking conflicts with native timers.

import { setupImportMocking } from '@nuxt/test-utils/module'

// Inside your Nuxt module or test setup environment
export default defineNuxtModule({
  setup(nuxt) {
    setupImportMocking(nuxt)
  }
})

Use createTest to generate a set of test hooks (beforeAll, afterAll, beforeEach, afterEach) and a test context (ctx) based on your provided TestOptions. This is useful for manual control over the Nuxt testing lifecycle in different test runners.

Supported options include:

• fixture: Whether to load a fixture.
• build: Whether to build the fixture.
• server: Whether to start a server (can accept an environment configuration).
• waitFor: A delay in milliseconds to wait before starting tests.
• browser: Whether to initialize a browser instance.
• teardownTimeout: A timeout in milliseconds for teardown operations.
• teardown: An array of functions to run during teardown.
• runner: Specifies the test runner (e.g., vitest, jest, bun, cucumber) to determine how hooks are applied.

import { createTest } from '@nuxt/test-utils/e2e'

const { beforeEach, afterEach, beforeAll, afterAll, ctx } = createTest({
  build: true,
  server: true,
  browser: true,
  teardownTimeout: 5000
})

// Use these hooks in your test runner's lifecycle configuration

Use renderSuspended to mount Vue components within a Nuxt environment. This utility is essential for testing components that use async setup(), rely on Nuxt-specific injections, or require access to Nuxt plugins.

renderSuspended acts as a wrapper around the render function from @testing-library/vue. Because it handles the Nuxt lifecycle and suspension, you should use it alongside @testing-library/vue utilities (like screen) to interact with the rendered output.

Key features:

• Supports async component setup.
• Provides access to Nuxt plugin injections.
• Allows setting a specific route via options.
• Returns a wrapper that includes a rerender method to update props asynchronously.

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

// Example 1: Rendering a single component
it('can render some component', async () => {
  const { html } = await renderSuspended(SomeComponent)
  expect(html()).toMatchInlineSnapshot(
    'This is an auto-imported component'
  )
})

// Example 2: Rendering an App with a specific route
import { screen } from '@testing-library/vue'

it('can also mount an app', async () => {
  const { html } = await renderSuspended(App, { route: '/test' })
  expect(screen.getByRole('link', { name: 'Test Link' })).toBeVisible()
})

Use mockNuxtImport to mock Nuxt's auto-import functionality. This allows you to intercept calls to composables or other auto-imported functions.

Usage Patterns:

• Mock by name: Pass the string name of the import and a factory function.
• Mock by reference: Pass the actual function/object and a factory function.
• Partial mock: Use the factory to wrap the original implementation (e.g., with vi.fn()).

Note: mockNuxtImport is a macro and must be transpiled by your build tool to work correctly.

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

// Mocking by name
mockNuxtImport('useStorage', () => {
 return () => {
   return { value: 'mocked storage' }
 }
})

// Mocking by reference
// (Assuming useStorage is available in the scope)
// mockNuxtImport(useStorage, () => {
//   return () => {
//     return { value: 'mocked storage' }
//   }
// })

// Making a partial mock with the original implementation
// mockNuxtImport('useRoute', original => vi.fn(original))