Nuxt Test Utils, the official testing library for the Vue-based Nuxt framework, has released version 4.0.0, its first major release in the lifetime of the consolidated package. Published on February 7, 2026, the release is built around a single dependency requirement: Vitest v4. That upgrade from the previously required Vitest v3 drives almost every significant change in the release, including architectural shifts to how test environments are initialised and how mocks are applied.
The most consequential change in v4.0.0 is that Nuxt's test environment setup has been moved from setupFiles to the beforeAll hook. In previous versions, this timing meant that vi.mock and mockNuxtImport calls couldn't reliably intercept composables used inside middleware or plugins, because those composables were often evaluated before mocks had taken effect. The change fixes a pair of long-standing issues in the repository, both filed by users reporting that module-level mocks were being silently ignored. With setup deferred to beforeAll, mocks are registered before Nuxt starts, making mock behaviour consistent and predictable across the test suite.
This does carry a migration cost. Code that calls Nuxt composables at the top level of a describe block, such as useRouter() or useNuxtApp(), will now throw [nuxt] instance unavailable because the environment is not yet initialised at that point. The fix is to move those calls inside beforeAll:
describe('router test', () => {
let router: ReturnType<typeof useRouter>
beforeAll(() => {
router = useRouter()
})
})
The second notable improvement is to mockNuxtImport, which now passes the original implementation to the factory function. This makes partial mocking substantially cleaner: instead of constructing a complete mock from scratch, tests can wrap or extend the real implementation and then narrow behaviour per-test.
Two targeted fixes round out the registerEndpoint utility. Endpoints registered inside setup files were previously lost when modules reset between tests; that state management gap has been closed. Additionally, endpoints that include query parameters in their URL patterns now match correctly, resolving a class of failures in tests using parameterised API paths.
A stricter approach to mock exports arrives as part of the Vitest v4 upgrade. Previously, accessing an export from a mocked module that the factory function did not explicitly return would silently yield undefined. Under Vitest v4 it throws instead. The recommended fix is to spread importOriginal into the factory return, making all original exports available by default and only overriding what the test needs.
Peer dependency requirements have been tightened across the board. happy-dom now requires version 20.0.11 or later, jsdom requires 27.4.0 or later, and @jest/globals drops support for versions below 30.0.0. @cucumber/cucumber now requires version 11 or later. Teams with pinned versions of these tools will need to update them alongside the Vitest v4 upgrade.
Nuxt Test Utils occupies a distinct space in the Vue testing landscape. While @vue/test-utils handles component-level unit testing in isolation, and Playwright or Cypress cover browser-based end-to-end scenarios, @nuxt/test-utils bridges both: it can spin up a full Nuxt application in a test environment, run server-side rendering checks, and mount components with the full Nuxt plugin and composable context in place.
Teams migrating from v3 can follow the official testing documentation at nuxt.com/docs/getting-started/testing alongside the v4.0.0 release notes. Teams previously using the now-retired nuxt-vitest package can find the older consolidation migration steps in the GitHub migration issue.
Nuxt Test Utils is an open-source library maintained by the Nuxt core team, led by Daniel Roe, and is published under the MIT license. It accumulates over 470,000 weekly npm downloads and is used across the Nuxt module ecosystem to provide consistent, framework-aware test coverage for application code and module authors alike.