feat!: support nested projects (Instagram Post Ideas For Information)

Author: Blank Bluf Template

docs/config/projects.md

@@ -3,9 +3,11 @@ title: projects | Config
 outline: deep
 ---
 
-# projects <CRoot />
+# projects
 
 - **Type:** `TestProjectConfiguration[]`
 - **Default:** `[]`
 
 An array of [projects](/guide/projects).
+
+A config file that declares `projects` doesn't run tests itself, it only provides the projects that do. This also applies to project config files: a referenced config that declares `projects` becomes a container for [nested projects](/guide/projects#nested-projects). The option is not supported inside an inline project configuration.

docs/guide/migration.md

@@ -110,6 +110,34 @@ export default defineConfig({
 })
 ```
 
+### Referenced Config Files Can Define Their Own Projects
+
+A config file referenced in [`test.projects`](/guide/projects) that declares `projects` itself is now treated like the root config: it doesn't run tests on its own, it only provides the [nested projects](/guide/projects#nested-projects) it declares. Their names are prefixed with the name of the declaring config, e.g. `app (unit)`.
+
+In Vitest 4 the `projects` field of a referenced config was silently ignored and the config ran as a single project. Check that your project configs don't carry a `projects` field unknowingly. The most common way to do that is merging a config that defines it:
+
+```ts [packages/app/vitest.config.ts]
+import { defineProject, mergeConfig } from 'vitest/config'
+import rootConfig from '../../vitest.config' // [!code --]
+import sharedConfig from '../../vitest.shared' // [!code ++]
+
+export default mergeConfig(
+ // the root config defines `test.projects`, so merging it
+ // would turn this project into a container for those projects
+ rootConfig, // [!code --]
+ sharedConfig, // [!code ++]
+ defineProject({
+ test: {
+ environment: 'jsdom',
+ },
+ }),
+)
+```
+
+Since the inherited `projects` paths resolve relative to the referenced config, this misconfiguration usually fails loudly at startup with `Projects definition references a non-existing file or a directory`, `No projects were found in "..."`, or a circular `projects` definition error.
+
+Inline configurations continue to ignore the `projects` field at runtime, but it is now also excluded from their `ProjectConfig` type.
+
 ### Hoisted Mocking Calls Must Be at the Top Level
 
 [`vi.mock`](/api/vi#vi-mock), [`vi.unmock`](/api/vi#vi-unmock), and [`vi.hoisted`](/api/vi#vi-hoisted) are hoisted to the top of the file and run before any surrounding code. Calling them inside a function, block, or `describe`/`test` callback previously only logged a warning. Vitest 5.0 now throws, because the call does not execute where it is written:

docs/guide/projects.md

@@ -324,3 +324,70 @@ Some of the configuration options are not allowed in a project config. Most nota
 
 All configuration options that are not supported inside a project configuration are marked with a <CRoot /> icon next to their name. They can only be defined once in the root config file.
 :::
+
+## Nested Projects
+
+A project referenced as a config file (or a directory containing one) can declare `projects` itself. Such a config behaves like the root config: it doesn't run any tests on its own, it only provides the projects that do. This makes it possible to reference a workspace that already defines its own projects:
+
+```ts [vitest.config.ts]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+ test: {
+ projects: ['./packages/app/vitest.config.ts'],
+ },
+})
+```
+
+```ts [packages/app/vitest.config.ts]
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+ test: {
+ name: 'app',
+ projects: [
+ {
+ test: {
+ name: 'unit',
+ include: ['**/*.unit.test.ts'],
+ },
+ },
+ {
+ test: {
+ name: 'e2e',
+ include: ['**/*.e2e.test.ts'],
+ },
+ },
+ ],
+ },
+})
+```
+
+Nested projects work the same way as projects defined in the root config: inline configurations extend the config that declares them (the `app` config here, not the root one), `extends` paths are resolved relative to it, and its own `globalSetup` is inherited by the extending projects [like any other non-root config](#configuration).
+
+The names of nested projects are prefixed with the name of the config that declares them, so the example above creates the `app (unit)` and `app (e2e)` projects. The `--project` filter matches the prefix as well: `--project app` runs every project of the `app` config, while `--project "app (unit)"` runs only one of them.
+
+To also run the tests of the config that declares `projects`, reference its own config file:
+
+```ts [packages/app/vitest.config.ts]
+import { defineProject } from 'vitest/config'
+
+export default defineProject({
+ test: {
+ name: 'app',
+ include: ['**/*.test.ts'],
+ projects: [
+ // the "app" project runs its own "include" alongside "app (unit)"
+ './vitest.config.ts',
+ {
+ test: {
+ name: 'unit',
+ include: ['**/*.unit.test.ts'],
+ },
+ },
+ ],
+ },
+})
+```
+
+Note that only config files can define nested projects. The `projects` option inside an inline configuration is not supported.

packages/vitest/src/node/core.ts

@@ -335,11 +335,18 @@ export class Vitest {
  await this._restart()
  }
 
+ // container configs have no Vite server (and might be outside the root),
+ // so their files are watched explicitly
+ if (resolved._containerConfigFiles?.length) {
+ server.watcher.add(resolved._containerConfigFiles)
+ }
+
  // since we set `server.hmr: false`, Vite does not auto restart itself
  server.watcher.on('change', async (file) => {
  file = normalize(file)
  const isConfig = file === server.config.configFile
  || this.projects.some(p => p.vite.config.configFile === file)
+ || this.config._containerConfigFiles?.includes(file)
  if (isConfig) {
  await this._restart('config')
  }