Nuxt/docs/content/2.guide/6.going-further/7.testing.md

192 lines
4.5 KiB
Markdown
Raw Normal View History

2022-03-30 16:00:08 +00:00
# Testing
::alert{icon=👉}
Test utils are still in development and the API and behavior may change. Currently, it's for module authors to preview but not yet ready for testing production apps.
2022-03-30 16:00:08 +00:00
::
In Nuxt 3, we have a rewritten version of `@nuxt/test-utils` available as `@nuxt/test-utils-edge`. We support [Vitest](https://github.com/vitest-dev/vitest) and [Jest](https://jestjs.io/) as the test runner.
## Installation
```bash
yarn add --dev @nuxt/test-utils-edge vitest
```
## Setup
In each `describe` block where you are taking advantage of the `@nuxt/test-utils` helper methods, you will need to set up the test context before beginning.
2022-03-30 16:00:08 +00:00
```ts
import { describe, test } from 'vitest'
import { setup, $fetch } from '@nuxt/test-utils-edge'
2022-06-20 16:53:45 +00:00
describe('My test', async () => {
2022-03-30 16:00:08 +00:00
await setup({
// test context options
})
test('my test', () => {
// ...
})
})
```
Behind the scenes, `setup` performs a number of tasks in `beforeAll`, `beforeEach`, `afterEach` and `afterAll` to set up the Nuxt test environment correctly.
2022-03-30 16:00:08 +00:00
## Options
### Nuxt Configuration
2022-03-30 16:00:08 +00:00
#### `rootDir`
2022-03-30 16:00:08 +00:00
Path to a directory with a Nuxt app to be put under test.
* Type: `string`
* Default: `'.'`
#### `configFile`
2022-03-30 16:00:08 +00:00
Name of the configuration file.
* Type: `string`
2022-07-13 17:02:33 +00:00
* Default: `'nuxt.config'`
2022-03-30 16:00:08 +00:00
<!--
2022-03-30 16:00:08 +00:00
#### config
Object with configuration overrides.
* Type: `NuxtConfig`
* Default: `{}` -->
### Setup Timings
2022-03-30 16:00:08 +00:00
#### `setupTimeout`
2022-03-30 16:00:08 +00:00
The amount of time (in milliseconds) to allow for `setupTest` to complete its work (which could include building or generating files for a Nuxt application, depending on the options that are passed).
* Type: `number`
* Default: `60000`
### Features to Enable
2022-03-30 16:00:08 +00:00
#### `server`
2022-03-30 16:00:08 +00:00
Whether to launch a server to respond to requests in the test suite.
* Type: `boolean`
* Default: `true`
#### `build`
2022-03-30 16:00:08 +00:00
Whether to run a separate build step.
* Type: `boolean`
* Default: `true` (`false` if `browser` or `server` is disabled)
#### `browser`
2022-03-30 16:00:08 +00:00
Under the hood, Nuxt test utils uses [`playwright`](https://playwright.dev/) to carry out browser testing. If this option is set, a browser will be launched and can be controlled in the subsequent test suite. (More info can be found [here](/guide/going-further/testing).)
2022-03-30 16:00:08 +00:00
* Type: `boolean`
* Default: `false`
#### `browserOptions`
2022-03-30 16:00:08 +00:00
* Type: `object` with the following properties
* **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/#version=master&path=docs%2Fapi.md&q=browsertypelaunchoptions).
#### `runner`
2022-03-30 16:00:08 +00:00
Specify the runner for the test suite. Currently, [Vitest](https://vitest.dev/) is recommended.
2022-03-30 16:00:08 +00:00
* Type: `'vitest' | 'jest'`
* Default: `'vitest'`
## APIs
### APIs for Rendering Testing
2022-03-30 16:00:08 +00:00
#### `$fetch(url)`
2022-03-30 16:00:08 +00:00
Get the HTML of a server-rendered page.
```ts
import { $fetch } from '@nuxt/test-utils'
const html = await $fetch('/')
```
#### `fetch(url)`
2022-03-30 16:00:08 +00:00
Get the response of a server-rendered page.
```ts
import { fetch } from '@nuxt/test-utils'
const res = await fetch('/')
const { body, headers } = res
```
#### `url(path)`
2022-03-30 16:00:08 +00:00
Get the full URL for a given page (including the port the test server is running on.)
```ts
import { url } from '@nuxt/test-utils'
const pageUrl = url('/page')
// 'http://localhost:6840/page'
```
## Testing Modules
### Fixture Setup
To test the modules we create, we could set up some Nuxt apps as fixtures and test their behaviors. For example, we can create a simple Nuxt app under `./test/fixture` with the configuration like:
2022-03-30 16:00:08 +00:00
```ts
// nuxt.config.js
import { defineNuxtConfig } from 'nuxt'
2022-03-30 16:00:08 +00:00
import MyModule from '../../src'
export default defineNuxtConfig({
modules: [
MyModule
]
})
```
### Tests Setup
We can create a test file and use the `rootDir` to test the fixture.
```ts
// basic.test.js
import { describe, it, expect } from 'vitest'
import { fileURLToPath } from 'node:url'
2022-03-30 16:00:08 +00:00
import { setup, $fetch } from '@nuxt/test-utils-edge'
describe('ssr', async () => {
await setup({
rootDir: fileURLToPath(new URL('./fixture', import.meta.url)),
})
it('renders the index page', async () => {
// Get response to a server-rendered page with `$fetch`.
const html = await $fetch('/')
expect(html).toContain('<a>A Link</a>')
})
})
```
For more usage, please refer to our [tests for Nuxt 3 framework](https://github.com/nuxt/framework/blob/main/test/basic.test.ts).
2022-03-30 16:00:08 +00:00
## Testing in a Browser
2022-03-30 16:00:08 +00:00
::alert{icon=🚧}
We are working on it, stay tuned!
::