@nuxt/docs-nightly 4.0.3-29239650.0f98b653 → 4.0.4-29239870.6bc9dccf

package/1.getting-started/17.testing.md

@@ -54,10 +54,28 @@ We currently ship an environment for unit testing code that needs a [Nuxt](https
 2. Create a `vitest.config.ts` with the following content:
 
    ```ts twoslash
-   import { defineVitestConfig } from '@nuxt/test-utils/config'
+   import { defineConfig } from 'vitest/config'
+   import { defineVitestProject } from '@nuxt/test-utils/config'
 
-   export default defineVitestConfig({
-     // any custom Vitest config you require
+   export default defineConfig({
+     test: {
+       projects: [
+         {
+           test: {
+             name: 'unit',
+             include: ['test/{e2e,unit}/*.{test,spec}.ts'],
+             environment: 'node',
+           },
+         },
+         await defineVitestProject({
+           test: {
+             name: 'nuxt',
+             include: ['test/nuxt/*.{test,spec}.ts'],
+             environment: 'nuxt',
+           },
+         }),
+       ],
+     },
    })
    ```
 
@@ -72,24 +90,16 @@ It is possible to set environment variables for testing by using the `.env.test`
 
 ### Using a Nuxt Runtime Environment
 
-By default, `@nuxt/test-utils` will not change your default Vitest environment, so you can do fine-grained opt-in and run Nuxt tests together with other unit tests.
-
-You can opt in to a Nuxt environment by adding `.nuxt.` to the test file's name (for example, `my-file.nuxt.test.ts` or `my-file.nuxt.spec.ts`) or by adding `@vitest-environment nuxt` as a comment directly in the test file.
+Using [Vitest projects](https://vitest.dev/guide/projects.html#test-projects), you have fine-grained control over which tests run in which environment:
 
-   ```ts twoslash
-   // @vitest-environment nuxt
-   import { test } from 'vitest'
+- **Unit tests**: Place regular unit tests in `test/unit/` - these run in a Node environment for speed
+- **Nuxt tests**: Place tests that rely on the Nuxt runtime environment in `test/nuxt/` - these will run within a Nuxt runtime environment
 
-   test('my test', () => {
-     // ... test with Nuxt environment!
-   })
-   ```
+#### Alternative: Simple Setup
 
-You can alternatively set `environment: 'nuxt'` in your Vitest configuration to enable the Nuxt environment for **all tests**.
+If you prefer a simpler setup and want all tests to run in the Nuxt environment, you can use the basic configuration:
 
 ```ts twoslash
-// vitest.config.ts
-import { fileURLToPath } from 'node:url'
 import { defineVitestConfig } from '@nuxt/test-utils/config'
 
 export default defineVitestConfig({
@@ -109,7 +119,7 @@ export default defineVitestConfig({
 })
 ```
 
-If you have set `environment: 'nuxt'` by default, you can then opt _out_ of the [default environment](https://vitest.dev/guide/environment.html#test-environment) per test file as needed.
+If you're using the simple setup with `environment: 'nuxt'` by default, you can opt _out_ of the [Nuxt environment](https://vitest.dev/guide/environment.html#test-environment) per test file as needed.
 
 ```ts twoslash
 // @vitest-environment node
@@ -120,6 +130,45 @@ test('my test', () => {
 })
 ```
 
+::warning
+This approach is not recommended as it creates a hybrid environment where Nuxt Vite plugins run but the Nuxt entry and `nuxtApp` are not initialized. This can lead to hard-to-debug errors.
+::
+
+### Organizing Your Tests
+
+With the project-based setup, you might organize your tests as follows:
+
+```bash [Directory structure]
+test/
+├── e2e/
+│   └── ssr.test.ts
+├── nuxt/
+│   ├── components.test.ts
+│   └── composables.test.ts
+├── unit/
+│   └── utils.test.ts
+```
+
+You can of course opt for any test structure, but keeping the Nuxt runtime environment separated from Nuxt end-to-end tests is important for test stability.
+
+#### Running Tests
+
+With the project setup, you can run different test suites:
+
+```bash
+# Run all tests
+npx vitest
+
+# Run only unit tests
+npx vitest --project unit
+
+# Run only Nuxt tests
+npx vitest --project nuxt
+
+# Run tests in watch mode
+npx vitest --watch
+```
+
 ::warning
 When you run your tests within the Nuxt environment, they will be running in a [`happy-dom`](https://github.com/capricorn86/happy-dom) or [`jsdom`](https://github.com/jsdom/jsdom) environment. Before your tests run, a global Nuxt app will be initialized (including, for example, running any plugins or code you've defined in your `app.vue`).
 

package/2.guide/1.concepts/10.nuxt-lifecycle.md

@@ -68,7 +68,7 @@ In Nuxt, there are three types of middleware:
 - **Named route middleware**
 - **Anonymous (or inline) route middleware**
 
-Nuxt automatically executes global middleware for first time enter to the application and every time before route navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components.
+Nuxt executes all global middleware on the initial page load (both on server and client) and then again before any client-side navigation. Named and anonymous middleware are executed only on the routes specified in the middleware property of the page(route) meta defined in the corresponding page components.
 
 For details about each type and examples, see the [Middleware documentation](/docs/guide/directory-structure/middleware).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.0.3-29239650.0f98b653",
+  "version": "4.0.4-29239870.6bc9dccf",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",