Nuxt Test Utils v4 Released: Vitest v4 Integration, Mock Overhaul, and Stricter Environment Setup

The Nuxt team has released Nuxt Test Utils v4.0.0, the first major version release for the official Nuxt testing library. The update brings Vitest v4 as the sole dependency requirement and fundamentally restructures how testing environments and mocking work.

Key Changes

Environment Initialization Moved to beforeAll

The most impactful change moves Nuxt test environment setup from setupFiles to the beforeAll hook. This fixes two long-standing issues where module-level mocks were silently ignored because composables were executed before mocks took effect.

Migration required: Calling Nuxt composables (like useRouter(), useNuxtApp()) at the top of describe blocks will now throw errors. Move these calls into beforeAll.

Enhanced mockNuxtImport

The mockNuxtImport utility now passes the original implementation into the factory function, enabling simpler partial mocks -- wrap or extend real implementations instead of building from scratch.

registerEndpoint Fixes

• Fixed state management bug where endpoints registered in config files were lost between tests
• URL patterns with query parameters now match correctly

Stricter Mock Exports (Vitest v4)

Accessing mock module exports not explicitly returned by the factory now throws errors instead of silently returning undefined. Fix: spread importOriginal in factory return values.

Updated Peer Dependencies

• happy-dom: 20.0.11+
• jsdom: 27.4.0+
• @jest/globals: 30.0.0+
• @cucumber/cucumber: 11+

Why It Matters

Nuxt Test Utils occupies a unique position in the Vue testing ecosystem -- it bridges unit tests (@vue/test-utils) and E2E tests (Playwright/Cypress) by running a full Nuxt application in the test environment.

With 470K+ weekly npm downloads, this is a critical update for the Nuxt ecosystem. Teams should plan migration carefully due to the breaking changes in mock behavior and composable initialization timing.