Nitro Test Utils

The main goal for this package is to provide a simple and easy-to-use testing environment for Nitro applications, built on top of Vitest.

Features

• 🚀 Automatic Nitro server start and stop
• ↪️ Reruns tests on Nitro rebuild
• ✅ Seamless integration with Vitest
• 📡 Familiar $fetch helper like Nuxt test utils

Installation

Add the nitro-test-utils as well as vitest to your project with your favorite package manager:

# pnpm
pnpm add -D nitro-test-utils vitest

# npm
npm install -D nitro-test-utils vitest

# yarn
yarn add -D nitro-test-utils vitest

Basic Usage

Setting up the Nitro test environment for Vitest is as simple as creating a new vitest.config.ts configuration file in your project root.

import { defineConfig } from 'nitro-test-utils/config'

export default defineConfig()

[!TIP] Under the hood, the defineConfig function will automatically spin up a Nitro server in development mode before running your tests and shut it down afterwards.

Write your tests in a dedicated location, e.g. a tests directory. You can use the $fetch function to make requests to the Nitro server that is started by the test environment.

A simple example could look like this:

import { describe, expect, it } from 'vitest'
import { $fetch } from 'nitro-test-utils/e2e'

describe('routes', () => {
  it('responds successfully', async () => {
    const { body, status } = await $fetch('/api/health')

    expect(status).toBe(200)
    expect(body).toMatchSnapshot()
  })
})

[!NOTE] Whenever Nitro is rebuilt, the tests will rerun automatically.

Configuration

Nitro Root Directory

If your Nitro server is located in a different directory, you can specify the rootDir option in the Nitro configuration. It should be the path to the nitro.config.ts configuration file:

import { defineConfig } from 'nitro-test-utils/config'

export default defineConfig({
  nitro: {
    // Set the root directory of your Nitro app
    rootDir: 'my/server',
  },
})

By default, the Vitest working directory is used.

Development Vs. Production Build

By default, the Nitro server starts in development mode. This makes development easier, as Nitro will automatically reload when you make changes to your code and the tests will also automatically re-run.

To test the production build of your Nitro server, you can set the preset option in the vitest.config.ts configuration file:

import { defineConfig } from 'nitro-test-utils/config'

export default defineConfig({
  nitro: {
    // Set the preset to `node` for production build
    preset: 'node'
  },
})

Test Utilities

$fetch

The $fetch function is a simple wrapper around ofetch and is used to make requests to your Nitro server during tests. It will dynamically include the base URL of the test server.

Import the function from the nitro-test-utils/e2e module.

$fetch returns a promise that resolves with the following properties:

• body: The response body
• status: The response status code
• headers: The response headers

Usage:

Inside a test definition:

const { body, status, headers } = await $fetch('/api/hello')

expect(status).toBe(200)
expect(body).toMatchSnapshot()

Type Declaration:

declare function $fetch<T = any, R extends ResponseType = 'json'>(
  path: string,
  options?: FetchOptions<R>
): Promise<{
  body: T
  status: number
  headers: Record<string, string>
}>

[!TIP] Fetch options will be merged with the default options.

Roadmap

As of right now, the following features are planned:

• Make environment setup work within Nuxt projects
• Support .env.test files

License

MIT License © 2024-PRESENT Johann Schopplich