Nuxt Test Utils & E2E Testing
Relevant source files
The following files were used as context for generating this wiki page:
Nuxt Test Utils is a set of utilities designed to facilitate testing for Nuxt applications, supporting unit, integration, and end-to-end (E2E) testing environments. It provides a standardized way to initialize Nuxt instances, manage browser contexts via Playwright, and interact with the server using specialized fetch wrappers.
The testing infrastructure is primarily built around Vitest for test execution and Playwright for browser-based E2E scenarios. It supports complex testing requirements such as Hot Module Replacement (HMR) validation, runtime compiler checks, and server-side rendering (SSR) assertions.
Sources: packages/test-utils/README.md, test/utils.ts:1-10, vitest.config.ts:1-20
Core Testing Utilities
Nuxt provides several high-level functions to control the lifecycle of the application during a test run. These functions handle environment setup, server management, and browser interaction.
Test Environment Lifecycle
The setup function is the primary entry point for configuring the test environment. It accepts parameters to define the root directory, enable dev mode, or specify Nuxt configuration overrides.
The following table describes the primary utilities used across the E2E test suites:
| Function | Description | Source |
|---|---|---|
setup() | Initializes the Nuxt environment for the test suite. | test/basic.test.ts:16-35 |
renderPage() | Utility to open a new browser page and navigate to a path. | test/utils.ts:11-46 |
$fetch() | A wrapper around ofetch to make requests to the test server. | test/basic.test.ts:40 |
createPage() | Creates a new Playwright page instance. | test/basic.test.ts:684 |
useTestContext() | Provides access to the current active test configuration. | test/utils.ts:12 |
Sources: test/basic.test.ts:16-40, test/utils.ts:11-46
E2E Testing Patterns
E2E tests in the Nuxt repository typically verify hydration, client-side navigation, and server responses.
Browser Interaction and Assertions
Tests utilize Playwright's API (e.g., page.getByTestId, page.click) alongside custom Nuxt assertions. A common pattern is the use of renderPage to obtain a page object that tracks console logs, page errors, and network requests.
export async function renderPage (path = '/', opts?: { retries?: number }) {
const browser = await getBrowser()
const page = await browser.newPage({})
const pageErrors: Error[] = []
const requests: string[] = []
const consoleLogs: { type: string, text: string }[] = []
page.on('console', (message) => {
consoleLogs.push({ type: message.type(), text: message.text() })
})
page.on('pageerror', (err) => { pageErrors.push(err) })
// ... configuration ...
if (path) { await gotoPath(page, path, opts?.retries) }
return { page, pageErrors, requests, consoleLogs }
}
Sources: test/utils.ts:11-46
Hydration and Error Validation
Specific utilities like expectNoClientErrors ensure that a route renders without throwing JavaScript errors in the browser or logging warnings to the console. This is critical for verifying SSR/client hydration parity.
Sources: test/utils.ts:48-60
Testing Special Features
The repository includes dedicated test suites for advanced framework features like the Runtime Compiler and HMR.
Runtime Compiler Validation
The runtime-compiler.test.ts suite verifies that components defined with dynamic templates or scripts (e.g., templates retrieved from an API) function correctly within the Nuxt lifecycle.
Hot Module Replacement (HMR) Testing
HMR tests verify that changes to the file system are correctly reflected in the running dev server without a full page reload. This involves writing to fixture files and asserting on browser state changes.
Key HMR test scenarios:
- Style HMR: Updating
<style>blocks and checking computed CSS values in the browser. - Script HMR: Modifying reactive state logic and ensuring state persistence.
- Route HMR: Adding new
.vuefiles to thepages/directory and verifying the new route becomes reachable.
Sources: test/e2e/hmr.test.ts:25-110
Configuration and Project Matrix
The testing infrastructure uses a matrix approach to ensure compatibility across different bundlers and environments.
Vitest Project Matrix
The vitest.config.ts defines several project types, including:
- fixtures: Tests run against specific Nuxt app fixtures with various combinations of builders (Vite, Webpack, Rspack) and environments (dev, built).
- unit: Individual package tests.
- nuxt: Framework-level runtime tests.
const fixtureMatrix: FixtureMatrixEntry[] = [
{ env: 'dev', builder: 'vite', context: 'async', manifest: 'manifest-on' },
{ env: 'built', builder: 'webpack', context: 'default', manifest: 'manifest-on' },
// ... other combinations
]
Sources: vitest.config.ts:59-80
Multi-Platform Considerations
Tests account for platform differences, particularly Windows, by adjusting timeouts. For example, setupTimeout is often increased to 360 seconds on Windows compared to 120 seconds on other systems.
Sources: test/basic.test.ts:22, test/e2e/runtime-compiler.test.ts:18
Summary
Nuxt Test Utils provides a robust framework for validating both core framework functionality and application-level logic. By integrating Playwright for browser orchestration and Vitest for assertion execution, it enables comprehensive testing of SSR, hydration, and developer experience features like HMR across a wide matrix of build tools.