@nuxt/docs-nightly 5.0.0-29805631.e52272e5 → 5.0.0-29807902.5022deff

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

@@ -265,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'
 
@@ -286,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(`
@@ -306,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`
 
@@ -322,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'
@@ -342,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'
 
@@ -365,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`
 
@@ -658,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "5.0.0-29805631.e52272e5",
+  "version": "5.0.0-29807902.5022deff",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",