feat: deprecate workspace in favor of projects (#7923)

Co-authored-by: Ari Perkkiö <[email protected]>

Author: sheremet-va

README.md

@@ -43,7 +43,7 @@ Next generation testing framework powered by Vite.
 - Components testing ([Vue](https://github.com/vitest-tests/browser-examples/tree/main/examples/vue), [React](https://github.com/vitest-tests/browser-examples/tree/main/examples/react), [Svelte](https://github.com/vitest-tests/browser-examples/tree/main/examples/svelte), [Lit](./examples/lit), [Marko](https://github.com/marko-js/examples/tree/master/examples/library-ts))
 - Workers multi-threading via [Tinypool](https://github.com/tinylibs/tinypool) (a lightweight fork of [Piscina](https://github.com/piscinajs/piscina))
 - Benchmarking support with [Tinybench](https://github.com/tinylibs/tinybench)
-- [Workspace](https://vitest.dev/guide/workspace) support
+- [Projects](https://vitest.dev/guide/projects) support
 - [expect-type](https://github.com/mmkal/expect-type) for type-level testing
 - ESM first, top level await
 - Out-of-box TypeScript / JSX support

docs/.vitepress/components/FeaturesList.vue

@@ -13,7 +13,7 @@
     <ListItem>Workers multi-threading via <a target="_blank" href="https://github.com/tinylibs/tinypool" rel="noopener noreferrer">Tinypool</a></ListItem>
     <ListItem>Benchmarking support with <a target="_blank" href="https://github.com/tinylibs/tinybench" rel="noopener noreferrer">Tinybench</a></ListItem>
     <ListItem>Filtering, timeouts, concurrent for suite and tests</ListItem>
-    <ListItem><a href="/guide/workspace">Workspace</a> support</ListItem>
+    <ListItem><a href="/guide/projects">Projects</a> support</ListItem>
     <ListItem>
       <a href="/guide/snapshot">
         Jest-compatible Snapshot

docs/.vitepress/config.ts

@@ -477,8 +477,8 @@ function guide(): DefaultTheme.SidebarItem[] {
       link: '/guide/filtering',
     },
     {
-      text: 'Workspace',
-      link: '/guide/workspace',
+      text: 'Test Projects',
+      link: '/guide/projects',
     },
     {
       text: 'Reporters',

docs/advanced/api/index.md

@@ -119,7 +119,7 @@ If you pass down the config to the `startVitest` or `createVitest` APIs, Vitest
 :::
 
 ::: warning
-The `resolveConfig` doesn't resolve the `workspace`. To resolve workspace configs, Vitest needs an established Vite server.
+The `resolveConfig` doesn't resolve `projects`. To resolve projects configs, Vitest needs an established Vite server.
 
 Also note that `viteConfig.test` will not be fully resolved. If you need Vitest config, use `vitestConfig` instead.
 :::

docs/advanced/api/plugin.md

@@ -53,7 +53,7 @@ Vitest re-exports all Vite type-only imports via a `Vite` namespace, which you c
 ```
 :::
 
-Unlike [`reporter.onInit`](/advanced/api/reporters#oninit), this hooks runs early in Vitest lifecycle allowing you to make changes to configuration like `coverage` and `reporters`. A more notable change is that you can manipulate the global config from a [workspace project](/guide/workspace) if your plugin is defined in the project and not in the global config.
+Unlike [`reporter.onInit`](/advanced/api/reporters#oninit), this hooks runs early in Vitest lifecycle allowing you to make changes to configuration like `coverage` and `reporters`. A more notable change is that you can manipulate the global config from a [test project](/guide/projects) if your plugin is defined in the project and not in the global config.
 
 ## Context
 
@@ -107,7 +107,7 @@ const newProjects = await injectTestProjects({
 ```
 
 ::: warning Projects are Filtered
-Vitest filters projects during the config resolution, so if the user defined a filter, injected project might not be resolved unless it [matches the filter](./vitest#matchesprojectfilter). You can update the filter via the `vitest.config.project` option to always include your workspace project:
+Vitest filters projects during the config resolution, so if the user defined a filter, injected project might not be resolved unless it [matches the filter](./vitest#matchesprojectfilter). You can update the filter via the `vitest.config.project` option to always include your test project:
 
 ```ts
 vitest.config.project.push('my-project-name')

docs/advanced/api/test-project.md

@@ -4,10 +4,8 @@ title: TestProject
 
 # TestProject <Version>3.0.0</Version> {#testproject}
 
-- **Alias**: `WorkspaceProject` before 3.0.0
-
 ::: warning
-This guide describes the advanced Node.js API. If you just want to create a workspace, follow the ["Workspace"](/guide/workspace) guide.
+This guide describes the advanced Node.js API. If you just want to define projects, follow the ["Test Projects"](/guide/projects) guide.
 :::
 
 ## name
@@ -26,28 +24,34 @@ vitest.projects.map(p => p.name) === [
   'custom'
 ]
 ```
-```ts [vitest.workspace.js]
-export default [
-  './packages/server', // has package.json with "@pkg/server"
-  './utils', // doesn't have a package.json file
-  {
-    // doesn't customize the name
-    test: {
-      pool: 'threads',
-    },
-  },
-  {
-    // customized the name
-    test: {
-      name: 'custom',
-    },
+```ts [vitest.config.js]
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    projects: [
+      './packages/server', // has package.json with "@pkg/server"
+      './utils', // doesn't have a package.json file
+      {
+        // doesn't customize the name
+        test: {
+          pool: 'threads',
+        },
+      },
+      {
+        // customized the name
+        test: {
+          name: 'custom',
+        },
+      },
+    ],
   },
-]
+})
 ```
 :::
 
 ::: info
-If the [root project](/advanced/api/vitest#getroottestproject) is not part of a user workspace, its `name` will not be resolved.
+If the [root project](/advanced/api/vitest#getroottestproject) is not part of user projects, its `name` will not be resolved.
 :::
 
 ## vitest
@@ -279,7 +283,7 @@ dynamicExample !== staticExample // ✅
 :::
 
 ::: info
-Internally, Vitest uses this method to import global setups, custom coverage providers, workspace file, and custom reporters, meaning all of them share the same module graph as long as they belong to the same Vite server.
+Internally, Vitest uses this method to import global setups, custom coverage providers and custom reporters, meaning all of them share the same module graph as long as they belong to the same Vite server.
 :::
 
 ## onTestsRerun

docs/advanced/api/vitest.md

@@ -64,7 +64,7 @@ Benchmark mode calls `bench` functions and throws an error, when it encounters `
 
 ## config
 
-The root (or global) config. If workspace feature is enabled, projects will reference this as `globalConfig`.
+The root (or global) config. If projects are defined, they will reference this as `globalConfig`.
 
 ::: warning
 This is Vitest config, it doesn't extend _Vite_ config. It only has resolved values from the `test` property.
@@ -101,17 +101,17 @@ Cache manager that stores information about latest test results and test file st
 
 ## projects
 
-An array of [test projects](/advanced/api/test-project) that belong to the user's workspace. If the user did not specify a custom workspace, the workspace will only have a [root project](#getrootproject).
+An array of [test projects](/advanced/api/test-project) that belong to user's projects. If the user did not specify a them, this array will only contain a [root project](#getrootproject).
 
-Vitest will ensure that there is always at least one project in the workspace. If the user specifies a non-existent `--project` name, Vitest will throw an error.
+Vitest will ensure that there is always at least one project in this array. If the user specifies a non-existent `--project` name, Vitest will throw an error before this array is defined.
 
 ## getRootProject
 
 ```ts
 function getRootProject(): TestProject
 ```
 
-This returns the root test project. The root project generally doesn't run any tests and is not included in `vitest.projects` unless the user explicitly includes the root config in their workspace, or the workspace is not defined at all.
+This returns the root test project. The root project generally doesn't run any tests and is not included in `vitest.projects` unless the user explicitly includes the root config in their configuration, or projects are not defined at all.
 
 The primary goal of the root project is to setup the global config. In fact, `rootProject.config` references `rootProject.globalConfig` and `vitest.config` directly:
 
@@ -433,7 +433,7 @@ dynamicExample !== staticExample // ✅
 :::
 
 ::: info
-Internally, Vitest uses this method to import global setups, custom coverage providers, workspace file, and custom reporters, meaning all of them share the same module graph as long as they belong to the same Vite server.
+Internally, Vitest uses this method to import global setups, custom coverage providers, and custom reporters, meaning all of them share the same module graph as long as they belong to the same Vite server.
 :::
 
 ## close

docs/advanced/pool.md

@@ -31,12 +31,12 @@ export default defineConfig({
 })
 ```
 
-If you need to run tests in different pools, use the [workspace](/guide/workspace) feature:
+If you need to run tests in different pools, use the [`projects`](/guide/projects) feature:
 
 ```ts [vitest.config.ts]
 export default defineConfig({
   test: {
-    workspace: [
+    projects: [
       {
         extends: true,
         test: {
@@ -48,10 +48,6 @@ export default defineConfig({
 })
 ```
 
-::: info
-The `workspace` field was introduced in Vitest 3. To define a workspace in [Vitest 2](https://v2.vitest.dev/), create a separate `vitest.workspace.ts` file.
-:::
-
 ## API
 
 The file specified in `pool` option should export a function (can be async) that accepts `Vitest` interface as its first option. This function needs to return an object matching `ProcessPool` interface:
@@ -69,7 +65,7 @@ export interface ProcessPool {
 
 The function is called only once (unless the server config was updated), and it's generally a good idea to initialize everything you need for tests inside that function and reuse it when `runTests` is called.
 
-Vitest calls `runTest` when new tests are scheduled to run. It will not call it if `files` is empty. The first argument is an array of [TestSpecifications](/advanced/api/test-specification). Files are sorted using [`sequencer`](/config/#sequence-sequencer) before `runTests` is called. It's possible (but unlikely) to have the same file twice, but it will always have a different project - this is implemented via [`vitest.workspace.ts`](/guide/workspace) configuration.
+Vitest calls `runTest` when new tests are scheduled to run. It will not call it if `files` is empty. The first argument is an array of [TestSpecifications](/advanced/api/test-specification). Files are sorted using [`sequencer`](/config/#sequence-sequencer) before `runTests` is called. It's possible (but unlikely) to have the same file twice, but it will always have a different project - this is implemented via [`projects`](/guide/projects) configuration.
 
 Vitest will wait until `runTests` is executed before finishing a run (i.e., it will emit [`onFinished`](/advanced/reporters) only after `runTests` is resolved).
 

docs/advanced/runner.md

@@ -164,7 +164,7 @@ interface File extends Suite {
    */
   filepath: string
   /**
-   * The name of the workspace project the file belongs to.
+   * The name of the test project the file belongs to.
    */
   projectName: string | undefined
   /**

docs/blog/vitest-3.md

@@ -72,7 +72,7 @@ You can follow the design process in [#7069](https://github.com/vitest-dev/vites
 
 ## Inline Workspace
 
-Rejoice! No more separate files to define your [workspace](/guide/workspace) - specify an array of projects using the `workspace` field in your `vitest.config` file:
+Rejoice! No more separate files to define your [workspace](/guide/projects) - specify an array of projects using the `workspace` field in your `vitest.config` file:
 
 ```jsx
 import { defineConfig } from 'vitest/config'