Vitest integration with Nuxt


npm versionnpm downloadsGithub ActionsCodecov

A vitest environment for testing code that needs a Nuxt runtime environment

Warning This library is in active development and you should pin the patch version before using.


  1. First install nuxt-vitest:
pnpm add -D nuxt-vitest# oryarn add --dev nuxt-vitestnpm i -D nuxt-vitest
  1. Add nuxt-vitest to your nuxt.config.js:
export default defineNuxtConfig({  // ...  modules: [    'nuxt-vitest'  ]})
  1. Then create a vitest.config.mjs with the following content:
import { defineVitestConfig } from 'nuxt-vitest/config'export default defineVitestConfig({  // any custom vitest config you require})
  1. Setting environment for your tests

By default, nuxt-vitest will not change your default Vitest environment, so you can do fine-grain opt-in and run Nuxt tests together with other unit tests.

We provided a filename convention that test files contains .nuxt., like *.nuxt.test.{js,ts} and *.nuxt.spec.{js,ts}, will be run in Nuxt environment automatically.

Or you can add @vitest-environment nuxt in your test file as a comment to opt-in per test file.

// @vitest-environment nuxtimport { test } from 'vitest'test('my test', () => {  // ... test with Nuxt environment!})

Finally, you can set environment: 'nuxt', to enable Nuxt environment for all tests.

// vitest.config.tsimport { defineVitestConfig } from 'nuxt-vitest/config'export default defineVitestConfig({  test: {    environment: 'nuxt'  }})

👉 Important notes

When you run your tests within the Nuxt environment, they will be running in a happy-dom environment. Before your tests run, a global Nuxt app will be initialised (including, for example, running any plugins or code you've defined in your app.vue).

This means you should be take particular care not to mutate the global state in your tests (or, if you have, to reset it afterwards).

🛠️ Helpers

nuxt-vitest provides a number of helpers to make testing Nuxt apps easier.


// TODO:


mockNuxtImport allows you to mock Nuxt's auto import functionality. For example, to mock useStorage, you can do so like this:

import { mockNuxtImport } from 'nuxt-vitest/utils'mockNuxtImport('useStorage', () => {  return () => {    return { value: 'mocked storage' }  }})// your tests here


mockComponent allows you to mock Nuxt's component. The first argument can be the component name in PascalCase, or the relative path of the component. The second argument can is a factory function that returns the mocked component.

For example, to mock MyComponent, you can:

import { mockComponent } from 'nuxt-vitest/utils'mockComponent('MyComponent', {  props: {    value: String  },  setup(props) {    // ...  }})// relative path or alias also worksmockComponent('~/components/my-component.vue', async () => {  // or a factory function  return {    setup(props) {      // ...    }  }})// or you can use SFC for redirecting to a mock componentmockComponent('MyComponent', () => import('./MockComponent.vue'))// your tests here

Note: You can't reference to local variables in the factory function since they are hoisted. If you need to access Vue APIs or other variables, you need to import them in your factory function.

mockComponent('MyComponent', async () => {  const { ref, h } = await import('vue')  return {    setup(props) {      const counter = ref(0)      return () => h('div', null, counter.value)    }  }})

💻 Development

  • Clone this repository
  • Enable Corepack using corepack enable (use npm i -g corepack for Node.js < 16.10)
  • Install dependencies using pnpm install
  • Stub the library using pnpm dev:prepare
  • Run interactive tests using pnpm test


Made with ❤️

Published under the MIT License.