@nuxt/docs-nightly 4.5.1-29752449.30d24817 → 4.5.2-2610052030-052d82e

package/1.getting-started/17.testing.md

@@ -5,7 +5,7 @@ navigation.icon: i-lucide-circle-check
 ---
 
 ::tip
-If you are a module author, you can find more specific information in the [Module Author's guide](/docs/4.x/guide/modules/testing).
+If you are a module author, you can find more specific information in the [Module Author's guide](/docs/guide/modules/testing).
 ::
 
 Nuxt offers first-class support for end-to-end and unit testing of your Nuxt application via `@nuxt/test-utils`, a library of test utilities and configuration that currently powers the [tests we use on Nuxt itself](https://github.com/nuxt/nuxt/tree/main/test) and tests throughout the module ecosystem.
@@ -86,10 +86,14 @@ We currently ship an environment for unit testing code that needs a [Nuxt](https
    })
    ```
 
+    ::note
+    `defineVitestProject` is only for Nuxt-environment tests. End-to-end tests should be configured as a regular `test.environment: 'node'` project.
+    ::
+
 3. If your Nuxt-environment tests live outside `test/nuxt/`, see [TypeScript Support in Tests](#typescript-support-in-tests) to add them to the TypeScript context.
 
 ::tip
-When importing `@nuxt/test-utils` in your vitest config, It is necessary to have `"type": "module"` specified in your `package.json` or rename your vitest config file appropriately.
+When importing `@nuxt/test-utils` in your vitest config, it is necessary to have `"type": "module"` specified in your `package.json` or rename your vitest config file appropriately.
 > i.e., `vitest.config.m{ts,js}`.
 ::
 
@@ -163,7 +167,7 @@ You can of course opt for any test structure, but keeping the Nuxt runtime envir
 
 #### TypeScript Support in Tests
 
-By default, test files in `test/nuxt/` and `tests/nuxt/` directories are included in the [Nuxt app TypeScript context](/docs/4.x/guide/concepts/typescript#how-nuxt-uses-project-references). That means they will recognise Nuxt aliases (like `~/`, `@/`, `#imports`) and TypeScript will be aware of auto-imports that work in your Nuxt app.
+By default, test files in `test/nuxt/` and `tests/nuxt/` directories are included in the [Nuxt app TypeScript context](/docs/guide/concepts/typescript#how-nuxt-uses-project-references). That means they will recognise Nuxt aliases (like `~/`, `@/`, `#imports`) and TypeScript will be aware of auto-imports that work in your Nuxt app.
 
 ::tip
 This matches the recommended structure where only tests that need the Nuxt runtime environment are placed in these directories. Unit tests in other directories like `test/unit/` can be added manually if needed.
@@ -261,16 +265,15 @@ Under the hood, `mountSuspended` wraps `mount` from `@vue/test-utils`, so you ca
 
 For example:
 
-```ts twoslash
+```ts twoslash [tests/components/SomeComponents.nuxt.spec.ts]
 // @noErrors
-import { expect, it } from 'vitest'
 import type { Component } from 'vue'
 
 declare module '#components' {
   export const SomeComponent: Component
 }
 // ---cut---
-// tests/components/SomeComponents.nuxt.spec.ts
+import { expect, it } from 'vitest'
 import { mountSuspended } from '@nuxt/test-utils/runtime'
 import { SomeComponent } from '#components'
 
@@ -282,15 +285,11 @@ it('can mount some component', async () => {
 })
 ```
 
-```ts twoslash
-// @noErrors
+```ts twoslash [tests/App.nuxt.spec.ts]
 import { expect, it } from 'vitest'
-// ---cut---
-// tests/components/SomeComponents.nuxt.spec.ts
 import { mountSuspended } from '@nuxt/test-utils/runtime'
 import App from '~/app.vue'
 
-// tests/App.nuxt.spec.ts
 it('can also mount an app', async () => {
   const component = await mountSuspended(App, { route: '/test' })
   expect(component.html()).toMatchInlineSnapshot(`
@@ -302,9 +301,34 @@ it('can also mount an app', async () => {
 })
 ```
 
+If you need to spy on component setup state, you can set the `spy` option to `true` and access the return value of the setup via `setupState`.
+
+```ts twoslash [tests/components/SomeComponents.nuxt.spec.ts]
+// @noErrors
+import type { Component } from 'vue'
+
+declare module '#components' {
+  export const SomeComponent: Component
+}
+// ---cut---
+import { expect, it, vi } from 'vitest'
+import { mountSuspended } from '@nuxt/test-utils/runtime'
+import { SomeComponent } from '#components'
+
+it('can spy on setup state', async () => {
+  const component = await mountSuspended(SomeComponent, { spy: true })
+  vi.mocked(component.setupState.someMethod).mockImplementation(() => 'mocked')
+})
+```
+
 The options object accepts `@vue/test-utils` mount options and the following properties:
 
   - `route`: the initial route, or `false` to skip the initial route change (default `/`).
+  - `spy`: enable spy component setup state (default `false`).
+
+The return object includes the `@vue/test-utils` mount result and the following properties:
+
+  - `setupState`: the return value of the component setup.
 
 #### `renderSuspended`
 
@@ -318,16 +342,15 @@ The passed in component will be rendered inside a `<div id="test-wrapper"></div>
 
 Examples:
 
-```ts twoslash
+```ts twoslash [tests/components/SomeComponents.nuxt.spec.ts]
 // @noErrors
-import { expect, it } from 'vitest'
 import type { Component } from 'vue'
 
 declare module '#components' {
   export const SomeComponent: Component
 }
 // ---cut---
-// tests/components/SomeComponents.nuxt.spec.ts
+import { expect, it } from 'vitest'
 import { renderSuspended } from '@nuxt/test-utils/runtime'
 import { SomeComponent } from '#components'
 import { screen } from '@testing-library/vue'
@@ -338,11 +361,8 @@ it('can render some component', async () => {
 })
 ```
 
-```ts twoslash
-// @noErrors
+```ts twoslash [tests/App.nuxt.spec.ts]
 import { expect, it } from 'vitest'
-// ---cut---
-// tests/App.nuxt.spec.ts
 import { renderSuspended } from '@nuxt/test-utils/runtime'
 import App from '~/app.vue'
 
@@ -361,6 +381,11 @@ it('can also render an app', async () => {
 The options object accepts `@testing-library/vue` render options and the following properties:
 
   - `route`: the initial route, or `false` to skip the initial route change (default `/`).
+  - `spy`: enable spy component setup state (default `false`). See the [`mountSuspended`](#mountsuspended) example above.
+
+The return object includes the `@testing-library/vue` render result and the following properties:
+
+  - `setupState`: the return value of the component setup.
 
 #### `mockNuxtImport`
 
@@ -533,7 +558,7 @@ This object accepts the following properties:
 - `method`: (optional) HTTP method to match (e.g., 'GET', 'POST')
 - `once`: (optional) if true, the handler will only be used for the first matching request and then automatically removed
 
-> **Note**: If your requests in a component go to an external API, you can use `baseURL` and then make it empty using [Nuxt Environment Override Config](/docs/4.x/getting-started/configuration#environment-overrides) (`$test`) so all your requests will go to Nitro server.
+> **Note**: If your requests in a component go to an external API, you can use `baseURL` and then make it empty using [Nuxt Environment Override Config](/docs/getting-started/configuration#environment-overrides) (`$test`) so all your requests will go to Nitro server.
 
 #### Conflict with End-To-End Testing
 
@@ -654,6 +679,132 @@ If you prefer to use `@vue/test-utils` on its own for unit testing in Nuxt, and
 
 Congratulations, you're all set to start unit testing with `@vue/test-utils` in Nuxt! Happy testing!
 
+### Vitest Browser Mode
+
+`@nuxt/test-utils` provides helpers for testing in [Vitest Browser Mode](https://vitest.dev/guide/browser/) via `@nuxt/test-utils/browser`.
+
+#### Setup
+
+1. Install Vitest browser packages and a browser provider:
+
+   ::code-group{sync="pm"}
+   ```bash [npm]
+   npm i --save-dev @vitest/browser-playwright
+   ```
+   ```bash [yarn]
+   yarn add --dev @vitest/browser-playwright
+   ```
+   ```bash [pnpm]
+   pnpm add -D @vitest/browser-playwright
+   ```
+   ```bash [bun]
+   bun add --dev @vitest/browser-playwright
+   ```
+   ::
+
+2. Configure browser mode in your `vitest.config.ts`:
+
+   ```ts twoslash
+   // @errors: 2307
+   // ---cut---
+   import { defineConfig } from 'vitest/config'
+   import { defineVitestProject } from '@nuxt/test-utils/config'
+   import { playwright } from '@vitest/browser-playwright'
+
+   export default defineConfig({
+     test: {
+       projects: [
+         await defineVitestProject({
+           test: {
+             name: 'browser',
+             include: ['test/browser/**/*.{test,spec}.ts'],
+             browser: {
+               enabled: true,
+               provider: playwright(),
+               instances: [{ browser: 'chromium' }],
+             },
+             // If you want to enable `page.render` and automatic cleanup, add this setup file
+             setupFiles: ['@nuxt/test-utils/browser'],
+           },
+         }),
+       ],
+     },
+   })
+   ```
+
+   ::note
+   When adding `@nuxt/test-utils/browser` to `setupFiles`, if TypeScript does not automatically recognize the types for `page.render`, you can add `@nuxt/test-utils/browser` via `typescript.tsConfig.compilerOptions.types` in your `nuxt.config.ts`.
+   ::
+
+   ::note
+   If your Vitest browser mode tests live outside `test/nuxt/` (such as in `test/browser/`), see [Adding other test directories](#adding-other-test-directories) to add them to the TypeScript context.
+   ::
+
+#### Usage
+
+You can use `page.render` from `vitest/browser`:
+
+```ts twoslash [test/browser/components/MyCounter.nuxt.spec.ts]
+// @noErrors
+import type { Component } from 'vue'
+
+declare module '#components' {
+  export const MyCounter: Component
+}
+// ---cut---
+import { expect, it } from 'vitest'
+import { page } from 'vitest/browser'
+// If you added the setup file, the following import is not needed
+import '@nuxt/test-utils/browser'
+
+import { MyCounter } from '#components'
+
+it('counter button increments the count', async () => {
+  const screen = await page.render(MyCounter)
+  await screen.getByRole('button', { name: 'Increment' }).click()
+  await expect.element(screen.getByText('Count: 1')).toBeVisible()
+})
+```
+
+You can also import `render` directly from `@nuxt/test-utils/browser`:
+
+```ts twoslash
+// @noErrors
+import type { Component } from 'vue'
+
+declare module '#components' {
+  export const MyCounter: Component
+}
+// ---cut---
+import { expect, it } from 'vitest'
+import { render } from '@nuxt/test-utils/browser'
+import { MyCounter } from '#components'
+
+it('can render using the render helper', async () => {
+  const screen = await render(MyCounter)
+  await screen.getByRole('button', { name: 'Increment' }).click()
+  await expect.element(screen.getByText('Count: 1')).toBeVisible()
+})
+```
+
+The options object accepts `@vue/test-utils` mount options (use `container` instead of `attachTo`) and the following properties:
+
+  - `route`: the initial route, or `false` to skip the initial route change (default `/`).
+  - `spy`: enable spy component setup state (default `false`). See the [`mountSuspended`](#mountsuspended) example above.
+  - `container`: custom `HTMLElement` container to render into (use this option instead of `@vue/test-utils` `attachTo`).
+  - `baseElement`: custom base `HTMLElement` (default `document.body`).
+
+The return object includes the following properties:
+
+  - `container`: the container `HTMLElement` the component is rendered into.
+  - `baseElement`: the base `HTMLElement` (default `document.body`).
+  - `locator`: root element `Locator`.
+  - `setupState`: the return value of the component setup, mocked when the `spy` option is enabled.
+  - `debug()`: print formatted DOM to console.
+  - `unmount()`: unmount the component. Also records a `nuxt.unmount` trace mark.
+  - `emitted()`: get emitted events.
+  - `rerender(props)`: re-render the component with new props. Also records a `nuxt.rerender` trace mark.
+
 ## End-To-End Testing
 
 For end-to-end testing, we support [Vitest](https://github.com/vitest-dev/vitest), [Jest](https://jestjs.io), [Cucumber](https://cucumber.io/) and [Playwright](https://playwright.dev/) as test runners.
@@ -719,7 +870,7 @@ Please use the options below for the `setup` method.
   - Type: `number | undefined`
   - Default: `undefined`
 
-- `host`: If provided, a URL to use as the test target instead of building and running a new server. Useful for running "real" end-to-end tests against a deployed version of your application, or against an already running local server (which may provide a significant reduction in test execution timings). See the [target host end-to-end example below](/docs/4.x/getting-started/testing#target-host-end-to-end-example).
+- `host`: If provided, a URL to use as the test target instead of building and running a new server. Useful for running "real" end-to-end tests against a deployed version of your application, or against an already running local server (which may provide a significant reduction in test execution timings). See the [target host end-to-end example below](/docs/getting-started/testing#target-host-end-to-end-example).
   - Type: `string`
   - Default: `undefined`
 
@@ -734,6 +885,13 @@ Please use the options below for the `setup` method.
   - Type: `'vitest' | 'jest' | 'cucumber'`
   - Default: `'vitest'`
 
+- `logLevel`: Overrides the consola log level for the server subprocess. (use NUXT_TEST_LOG_LEVEL environment variable to override)
+  - Type: `number`
+  - Default: `1`
+- `captureServerLogs`: Whether to capture server process output instead of inheriting stdio. When `true` (default), server stdout/stderr is suppressed from the console and accessible via `getServerLogs()`. Set to `false` to restore the old inherit-stdio behaviour (useful when debugging a test locally).
+  - Type: `boolean`
+  - Default: `true`
+
 ##### Target `host` end-to-end example
 
 A common use-case for end-to-end testing is running the tests against a deployed application running in the same environment typically used for Production.
@@ -793,13 +951,34 @@ const pageUrl = url('/page')
 // 'http://localhost:6840/page'
 ```
 
+#### `getServerLogs()`
+
+Returns the lines captured from the server subprocess's stdout/stderr since the last `startServer()` call (or `clearServerLogs()`). Only populated when `captureServerLogs` is `true` (the default).
+
+```ts twoslash
+import { expect, it, vi } from 'vitest'
+import { $fetch, clearServerLogs, getServerLogs } from '@nuxt/test-utils/e2e'
+
+it('captures console.log output from a server route', async () => {
+  clearServerLogs()
+  await $fetch('/api/log-test')
+  await vi.waitFor(() => {
+    expect(getServerLogs().some(line => line.includes('[test] server-log-marker'))).toBe(true)
+  })
+})
+```
+
+#### `clearServerLogs()`
+
+Clears the captured server log lines. Useful between requests when you want to assert only on the logs produced by a specific operation.
+
 ### Testing in a Browser
 
 We provide built-in support using Playwright within `@nuxt/test-utils`, either programmatically or via the Playwright test runner.
 
 #### `createPage(url)`
 
-Within `vitest`, `jest` or `cucumber`, you can create a configured Playwright browser instance with `createPage`, and (optionally) point it at a path from the running server. You can find out more about the API methods available from [in the Playwright documentation](https://playwright.dev/docs/api/class-page).
+Within `vitest`, `jest` or `cucumber`, you can create a configured Playwright browser instance with `createPage`, and (optionally) point it at a path from the running server. You can find out more about the API methods available in the [Playwright documentation](https://playwright.dev/docs/api/class-page).
 
 ```ts twoslash
 import { createPage } from '@nuxt/test-utils/e2e'