Testing

👉

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.

In Nuxt 3, we have a rewritten version of @nuxt/test-utils available as @nuxt/test-utils-edge. We support Vitest and Jest as the test runner.

Installation

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.

import { describe, test } from 'vitest'
import { setup, $fetch } from '@nuxt/test-utils-edge'
describe('My test', () => {
  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.

Options

Nuxt configuration

rootDir

Path to a directory with a Nuxt app to be put under test.

• Type: string
• Default: '.'

configFile

Name of the configuration file.

• Type: string
• Default: `‘nuxt.config’

Setup timings

setupTimeout

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

server

Whether to launch a server to respond to requests in the test suite.

• Type: boolean
• Default: true

build

Whether to run a separate build step.

• Type: boolean
• Default: true (false if browser or server is disabled)

browser

Under the hood, Nuxt test utils uses playwright 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.)

• Type: boolean
• Default: false

browserOptions

• 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.

runner

Specify the runner for the test suite. Currently, Vitest is recommended.

• Type: 'vitest' | 'jest'
• Default: 'vitest'

APIs

APIs for rendering testing

$fetch(url)

Get the HTML of a server-rendered page.

import { $fetch } from '@nuxt/test-utils'
const html = await $fetch('/')

fetch(url)

Get the response of a server-rendered page.

import { fetch } from '@nuxt/test-utils'
const res = await fetch('/')
const { body, headers } = res

url(path)

Get the full URL for a given page (including the port the test server is running on.)

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:

// nuxt.config.js
import { defineNuxtConfig } from 'nuxt3'
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.

// basic.test.js
import { describe, it } from 'vitest'
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.

Testing in a browser

🚧

We are working on it, stay tuned!