diff --git a/docs/1.getting-started/11.testing.md b/docs/1.getting-started/11.testing.md index dba218d7dd94..67437c1a5f05 100644 --- a/docs/1.getting-started/11.testing.md +++ b/docs/1.getting-started/11.testing.md @@ -15,7 +15,7 @@ Nuxt offers first-class support for end-to-end and unit testing of your Nuxt app In order to allow you to manage your other testing dependencies, `@nuxt/test-utils` ships with various optional peer dependencies. For example: - you can choose between `happy-dom` and `jsdom` for a runtime Nuxt environment -- you can choose between `vitest` and `jest` for end-to-end test runners +- you can choose between `vitest`, `cucumber`, `jest` and `playwright` for end-to-end test runners - `playwright-core` is only required if you wish to use the built-in browser testing utilities ::code-group @@ -454,7 +454,7 @@ Please use the options below for the `setup` method. - `type`: The type of browser to launch - either `chromium`, `firefox` or `webkit` - `launch`: `object` of options that will be passed to playwright when launching the browser. See [full API reference](https://playwright.dev/docs/api/class-browsertype#browser-type-launch). - `runner`: Specify the runner for the test suite. Currently, [Vitest](https://vitest.dev) is recommended. - - Type: `'vitest' | 'jest'` + - Type: `'vitest' | 'jest' | 'cucumber'` - Default: `'vitest'` ### APIs @@ -505,3 +505,54 @@ import { createPage } from '@nuxt/test-utils/e2e' const page = await createPage('/page') // you can access all the Playwright APIs from the `page` variable ``` + +#### Testing with Playwright Test Runner + +We provide first-class support for using `@nuxt/test-utils` within a Playwright test runner. + +You can provide global Nuxt configuration, with the same configuration details as the `setup()` function mentioned earlier in this section. + +```ts [playwright.config.ts] +import { fileURLToPath } from 'node:url' +import { defineConfig, devices } from '@playwright/test' +import type { ConfigOptions } from '@nuxt/test-utils/playwright' + +export default defineConfig({ + use: { + nuxt: { + rootDir: fileURLToPath(new URL('.', import.meta.url)) + } + }, + // ... +}) +``` + +::read-more{title="See full example config" to="https://github.com/nuxt/test-utils/blob/main/examples/app-playwright/playwright.config.ts" target="_blank"} + +Your test file should then use `expect` and `test` directly from `@nuxt/test-utils/playwright`: + +```ts [tests/example.test.ts] +import { expect, test } from '@nuxt/test-utils/playwright' + +test('test', async ({ page, goto }) => { + await goto('/', { waitUntil: 'hydration' }) + await expect(page.getByRole('heading')).toHaveText('Welcome to Playwright!') +}) +``` + +You can alternatively configure your Nuxt server directly within your test file: + +```ts [tests/example.test.ts] +import { expect, test } from '@nuxt/test-utils/playwright' + +test.use({ + nuxt: { + rootDir: fileURLToPath(new URL('..', import.meta.url)) + } +}) + +test('test', async ({ page, goto }) => { + await goto('/', { waitUntil: 'hydration' }) + await expect(page.getByRole('heading')).toHaveText('Welcome to Playwright!') +}) +```