Hi @alpine yew. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
#When should I use renderSuspended? When should I use the Nuxt testing environment and when should I
tough oliveBOT
Nuxt’s docs and linked issues distinguish unit tests (Node / “plain” Vitest) from Nuxt tests (Nuxt environment / @nuxt/test-utils). The choice of environment (and helpers like renderSuspended / mountSuspended) follows that split.
1. When to use the Nuxt environment
Configure Vitest with projects so only some tests run with the Nuxt runtime loaded (middleware, plugins, auto‑imports, runtime config, etc.): [Vitest projects docs; Vitest project example]
// vitest.config.ts
export default defineConfig({
test: {
projects: [
// “unit” – plain Node env (no Nuxt runtime)
await defineVitestProject({
test: {
name: 'unit',
include: ['test/{e2e,unit}/*.{test,spec}.ts'],
environment: 'node',
},
}),
// “nuxt” – full Nuxt runtime
await defineVitestProject({
test: {
name: 'nuxt',
include: ['test/nuxt/*.{test,spec}.ts'],
environment: 'nuxt',
},
}),
],
},
});
Use the Nuxt environment when:
- You need Nuxt runtime features (pages/layouts, middleware, plugins, modules,
useState,useRoute,#imports,#components, etc.). - You want to test behavior that depends on Nuxt’s configuration or server rendering.
- You’re doing “integration‑style” tests of your app within Nuxt. [Nuxt tests vs unit tests; testing primer]
In that context you typically use helpers from @nuxt/test-utils/runtime like mountSuspended (and, by extension, renderSuspended / similar helpers) to mount components/pages with the Nuxt app bootstrapped and suspense resolved before assertions. [Supabase + mountSuspended example]
Because this environment loads middleware and config, it’s heavier; that’s expected and is why it’s usually reserved for a separate “nuxt” test project.
2. When to use plain Node / unit tests (no Nuxt env)
The Nuxt docs and comments explicitly say the unit test example is not meant to rely on Nuxt runtime variables or auto‑imports; if you rely on the Nuxt instance, those tests belong in the Nuxt folder/project instead. [Unit vs Nuxt tests clarification; unit example not using runtime]
Use plain Vitest / Node environment when:
- You test pure Vue components, composables, or utilities that don’t need Nuxt’s runtime.
- You want fast, isolated tests without middleware, plugins, or Nuxt config.
- You’re mocking external integrations (e.g. stubbing Vuetify transitions, mocking Supabase clients) and don’t need the full Nuxt app to run. [Vuetify transition stub in unit test; advice to treat composables as implementation detail, use black‑box style tests]
Nuxt 4+ will also automatically give you TypeScript path alias support (~/, @/, #imports) in test/ and tests/ in these unit tests, so you don’t need to pull in the Nuxt runtime just to get aliases. [TS path aliases for tests]
3. So when do I pick which?
A practical rule of thumb based on the docs and issues:
- Ask “Does this test need Nuxt runtime features?”
- No → write a unit test in the Node environment (fast, minimal, no middleware/config).
- Yes → write a Nuxt test in the Nuxt environment (placed in your
test/nuxtproject, usingmountSuspended/renderSuspendedas needed). [Vitest projects docs; unit vs Nuxt tests docs]
This separation is exactly why the Vitest projects setup is recommended and the older “simple” one‑size‑fits‑all config is deprecated: it prevents accidentally running everything with the Nuxt runtime when you only wanted light unit tests. [Clarified testing environments]