fix!: remove deprecated workspace option in favor of projects (#8218)

sheremet-va · web-flow · commit 76fb75d4248c · 2025-06-25T14:56:40.000+02:00
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -70,7 +70,6 @@ export default ({ mode }: { mode: string }) => {
           customIcon: {
             'CLI': 'vscode-icons:file-type-shell',
             'vitest.shims': 'vscode-icons:file-type-vitest',
-            'vitest.workspace': 'vscode-icons:file-type-vitest',
             'vitest.config': 'vscode-icons:file-type-vitest',
             '.spec.ts': 'vscode-icons:file-type-testts',
             '.test.ts': 'vscode-icons:file-type-testts',
diff --git a/docs/config/index.md b/docs/config/index.md
@@ -2362,20 +2362,6 @@ Relevant only when using with `shouldAdvanceTime: true`. increment mocked time b
 
 Tells fake timers to clear "native" (i.e. not fake) timers by delegating to their respective handlers. When disabled, it can lead to potentially unexpected behavior if timers existed prior to starting fake timers session.
 
-### workspace<NonProjectOption /> {#workspace}
-
-::: danger DEPRECATED
-This options is deprecated and will be removed in the next major. Please, use [`projects`](#projects) instead.
-:::
-
-- **Type:** `string | TestProjectConfiguration[]`
-- **CLI:** `--workspace=./file.js`
-- **Default:** `vitest.{workspace,projects}.{js,ts,json}` close to the config file or root
-
-Path to a [workspace](/guide/projects) config file relative to [root](#root).
-
-Since Vitest 3, you can also define the workspace array in the root config. If the `workspace` is defined in the config manually, Vitest will ignore the `vitest.workspace` file in the root.
-
 ### projects<NonProjectOption /> {#projects}
 
 - **Type:** `TestProjectConfiguration[]`
diff --git a/docs/guide/cli-generated.md b/docs/guide/cli-generated.md
@@ -272,13 +272,6 @@ High and low watermarks for functions in the format of `<high>,<low>`
 
 Override Vite mode (default: `test` or `benchmark`)
 
-### workspace
-
-- **CLI:** `--workspace <path>`
-- **Config:** [workspace](/config/#workspace)
-
-[deprecated] Path to a workspace configuration file
-
 ### isolate
 
 - **CLI:** `--isolate`
diff --git a/docs/guide/migration.md b/docs/guide/migration.md
@@ -122,6 +122,7 @@ Vitest 4.0 removes some deprecated APIs, including:
 
 - `poolMatchGlobs` config option. Use [`projects`](/guide/projects) instead.
 - `environmentMatchGlobs` config option. Use [`projects`](/guide/projects) instead.
+- `workspace` config option. Use [`projects`](/guide/projects) instead.
 
 ## Migrating from Jest {#jest}
 
diff --git a/packages/vitest/src/constants.ts b/packages/vitest/src/constants.ts
@@ -14,20 +14,12 @@ export const extraInlineDeps: RegExp[] = [
 
 export const CONFIG_NAMES: string[] = ['vitest.config', 'vite.config']
 
-const WORKSPACES_NAMES = ['vitest.workspace', 'vitest.projects']
-
 export const CONFIG_EXTENSIONS: string[] = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs']
 
 export const configFiles: string[] = CONFIG_NAMES.flatMap(name =>
   CONFIG_EXTENSIONS.map(ext => name + ext),
 )
 
-const WORKSPACES_EXTENSIONS = [...CONFIG_EXTENSIONS, '.json']
-
-export const workspacesFiles: string[] = WORKSPACES_NAMES.flatMap(name =>
-  WORKSPACES_EXTENSIONS.map(ext => name + ext),
-)
-
 export const globalApis: string[] = [
   // suite
   'suite',
diff --git a/packages/vitest/src/node/cli/cli-config.ts b/packages/vitest/src/node/cli/cli-config.ts
@@ -334,11 +334,6 @@ export const cliOptionsConfig: VitestCLIOptions = {
     description: 'Override Vite mode (default: `test` or `benchmark`)',
     argument: '<name>',
   },
-  workspace: {
-    description: '[deprecated] Path to a workspace configuration file',
-    argument: '<path>',
-    normalize: true,
-  },
   isolate: {
     description:
       'Run every test file in isolation. To disable isolation, use `--no-isolate` (default: `true`)',
diff --git a/packages/vitest/src/node/config/resolveConfig.ts b/packages/vitest/src/node/config/resolveConfig.ts
@@ -21,7 +21,6 @@ import {
   defaultInspectPort,
   defaultPort,
   extraInlineDeps,
-  workspacesFiles,
 } from '../../constants'
 import { benchmarkConfigDefaults, configDefaults } from '../../defaults'
 import { isCI, stdProvider } from '../../utils/env'
@@ -387,7 +386,6 @@ export function resolveConfig(
     // Configs
     resolved.config && slash(resolved.config),
     ...configFiles,
-    ...workspacesFiles,
 
     // Vite internal
     '**\/virtual:*',
@@ -598,14 +596,6 @@ export function resolveConfig(
     }
   }
 
-  if (typeof resolved.workspace === 'string') {
-    // if passed down from the CLI and it's relative, resolve relative to CWD
-    resolved.workspace
-      = typeof options.workspace === 'string' && options.workspace[0] === '.'
-        ? resolve(process.cwd(), options.workspace)
-        : resolvePath(resolved.workspace, resolved.root)
-  }
-
   if (!builtinPools.includes(resolved.pool as BuiltinPool)) {
     resolved.pool = resolvePath(resolved.pool, resolved.root)
   }
diff --git a/packages/vitest/src/node/core.ts b/packages/vitest/src/node/core.ts
@@ -11,16 +11,15 @@ import type { ResolvedConfig, TestProjectConfiguration, UserConfig, VitestRunMod
 import type { CoverageProvider } from './types/coverage'
 import type { Reporter } from './types/reporter'
 import type { TestRunResult } from './types/tests'
-import { promises as fs } from 'node:fs'
 import { getTasks, hasFailed } from '@vitest/runner/utils'
 import { SnapshotManager } from '@vitest/snapshot/manager'
 import { noop, toArray } from '@vitest/utils'
-import { dirname, join, normalize, relative, resolve } from 'pathe'
+import { normalize, relative } from 'pathe'
 import { ViteNodeRunner } from 'vite-node/client'
 import { ViteNodeServer } from 'vite-node/server'
 import { version } from '../../package.json' with { type: 'json' }
 import { WebSocketReporter } from '../api/setup'
-import { defaultBrowserPort, workspacesFiles as workspaceFiles } from '../constants'
+import { defaultBrowserPort } from '../constants'
 import { distDir } from '../paths'
 import { wildcardPatternToRegExp } from '../utils/base'
 import { convertTasksToEvents } from '../utils/tasks'
@@ -90,11 +89,6 @@ export class Vitest {
   /** @internal */ closingPromise?: Promise<void>
   /** @internal */ isCancelling = false
   /** @internal */ coreWorkspaceProject: TestProject | undefined
-  /**
-   * @internal
-   * @deprecated
-   */
-  resolvedProjects: TestProject[] = []
   /** @internal */ _browserLastPort = defaultBrowserPort
   /** @internal */ _browserSessions = new BrowserSessions()
   /** @internal */ _cliOptions: CliOptions = {}
@@ -114,7 +108,6 @@ export class Vitest {
   private _state?: StateManager
   private _cache?: VitestCache
   private _snapshot?: SnapshotManager
-  private _workspaceConfigPath?: string
 
   constructor(
     public readonly mode: VitestRunMode,
@@ -208,8 +201,6 @@ export class Vitest {
     this.pool = undefined
     this.closingPromise = undefined
     this.projects = []
-    this.resolvedProjects = []
-    this._workspaceConfigPath = undefined
     this.coverageProvider = undefined
     this.runningPromise = undefined
     this.coreWorkspaceProject = undefined
@@ -261,7 +252,6 @@ export class Vitest {
         file = normalize(file)
         const isConfig = file === server.config.configFile
           || this.projects.some(p => p.vite.config.configFile === file)
-          || file === this._workspaceConfigPath
         if (isConfig) {
           await Promise.all(this._onRestartListeners.map(fn => fn('config')))
           this.report('onServerRestart', 'config')
@@ -278,7 +268,6 @@ export class Vitest {
     catch { }
 
     const projects = await this.resolveProjects(this._cliOptions)
-    this.resolvedProjects = projects
     this.projects = projects
 
     await Promise.all(projects.flatMap((project) => {
@@ -404,38 +393,10 @@ export class Vitest {
     return this.runner.executeId(moduleId)
   }
 
-  private async resolveWorkspaceConfigPath(): Promise<string | undefined> {
-    if (typeof this.config.workspace === 'string') {
-      return this.config.workspace
-    }
-
-    const configDir = this.vite.config.configFile
-      ? dirname(this.vite.config.configFile)
-      : this.config.root
-
-    const rootFiles = await fs.readdir(configDir)
-
-    const workspaceConfigName = workspaceFiles.find((configFile) => {
-      return rootFiles.includes(configFile)
-    })
-
-    if (!workspaceConfigName) {
-      return undefined
-    }
-
-    return join(configDir, workspaceConfigName)
-  }
-
   private async resolveProjects(cliOptions: UserConfig): Promise<TestProject[]> {
     const names = new Set<string>()
 
     if (this.config.projects) {
-      if (typeof this.config.workspace !== 'undefined') {
-        this.logger.warn(
-          'Both `test.projects` and `test.workspace` are defined. Ignoring the `test.workspace` option.',
-        )
-      }
-
       return resolveProjects(
         this,
         cliOptions,
@@ -445,57 +406,17 @@ export class Vitest {
       )
     }
 
-    if (Array.isArray(this.config.workspace)) {
-      this.logger.deprecate(
-        'The `test.workspace` option is deprecated and will be removed in the next major. To hide this warning, rename `test.workspace` option to `test.projects`.',
-      )
-      return resolveProjects(
-        this,
-        cliOptions,
-        undefined,
-        this.config.workspace,
-        names,
-      )
-    }
-
-    const workspaceConfigPath = await this.resolveWorkspaceConfigPath()
-
-    this._workspaceConfigPath = workspaceConfigPath
-
-    // user doesn't have a workspace config, return default project
-    if (!workspaceConfigPath) {
-      // user can filter projects with --project flag, `getDefaultTestProject`
-      // returns the project only if it matches the filter
-      const project = getDefaultTestProject(this)
-      if (!project) {
-        return []
-      }
-      return resolveBrowserProjects(this, new Set([project.name]), [project])
+    if ('workspace' in this.config) {
+      throw new Error('The `test.workspace` option was removed in Vitest 4. Please, migrate to `test.projects` instead. See https://vitest.dev/guide/projects for examples.')
     }
 
-    const configFile = this.vite.config.configFile
-      ? resolve(this.vite.config.root, this.vite.config.configFile)
-      : 'the root config file'
-
-    this.logger.deprecate(
-      `The workspace file is deprecated and will be removed in the next major. Please, use the \`test.projects\` field in ${configFile} instead.`,
-    )
-
-    const workspaceModule = await this.import<{
-      default: TestProjectConfiguration[]
-    }>(workspaceConfigPath)
-
-    if (!workspaceModule.default || !Array.isArray(workspaceModule.default)) {
-      throw new TypeError(`Workspace config file "${workspaceConfigPath}" must export a default array of project paths.`)
+    // user can filter projects with --project flag, `getDefaultTestProject`
+    // returns the project only if it matches the filter
+    const project = getDefaultTestProject(this)
+    if (!project) {
+      return []
     }
-
-    return resolveProjects(
-      this,
-      cliOptions,
-      workspaceConfigPath,
-      workspaceModule.default,
-      names,
-    )
+    return resolveBrowserProjects(this, new Set([project.name]), [project])
   }
 
   /**
diff --git a/packages/vitest/src/node/projects/resolveProjects.ts b/packages/vitest/src/node/projects/resolveProjects.ts
@@ -1,6 +1,12 @@
 import type { GlobOptions } from 'tinyglobby'
 import type { Vitest } from '../core'
-import type { BrowserInstanceOption, ResolvedConfig, TestProjectConfiguration, UserConfig, UserWorkspaceConfig } from '../types/config'
+import type {
+  BrowserInstanceOption,
+  ResolvedConfig,
+  TestProjectConfiguration,
+  UserConfig,
+  UserWorkspaceConfig,
+} from '../types/config'
 import { existsSync, promises as fs } from 'node:fs'
 import os from 'node:os'
 import { limitConcurrency } from '@vitest/runner/utils'
diff --git a/packages/vitest/src/node/types/config.ts b/packages/vitest/src/node/types/config.ts
@@ -377,12 +377,6 @@ export interface InlineConfig {
    */
   projects?: TestProjectConfiguration[]
 
-  /**
-   * Path to a workspace configuration file
-   * @deprecated use `projects` instead
-   */
-  workspace?: string | TestProjectConfiguration[]
-
   /**
    * Update snapshot
    *
@@ -1110,7 +1104,6 @@ type NonProjectOptions =
   | 'maxWorkers'
   | 'minWorkers'
   | 'fileParallelism'
-  | 'workspace'
   | 'watchTriggerPatterns'
 
 export type ProjectConfig = Omit<
diff --git a/test/config/fixtures/workspace/browser/workspace-with-browser.ts b/test/config/fixtures/workspace/browser/workspace-with-browser.ts
diff --git a/test/config/fixtures/workspace/nested/e2e.projects.js b/test/config/fixtures/workspace/nested/e2e.projects.js
diff --git a/test/config/test/failures.test.ts b/test/config/test/failures.test.ts
@@ -310,7 +310,18 @@ Use either:
 test('v8 coverage provider cannot be used in workspace without playwright + chromium', async () => {
   const { stderr } = await runVitest({
     coverage: { enabled: true },
-    workspace: './fixtures/workspace/browser/workspace-with-browser.ts',
+    projects: [
+      {
+        test: {
+          name: 'Browser project',
+          browser: {
+            enabled: true,
+            provider: 'webdriverio',
+            instances: [{ browser: 'chrome' }],
+          },
+        },
+      },
+    ],
   }, {}, { fails: true })
   expect(stderr).toMatch(
     `Error: @vitest/coverage-v8 does not work with
@@ -585,3 +596,11 @@ test('minWorkers higher than maxWorkers does not crash', async ({ skip }) => {
   expect(stdout).toMatch('✓ example.test.ts > it works')
   expect(stderr).toBe('')
 })
+
+test('cannot set the `workspace` options', async () => {
+  const { stderr } = await runVitest({
+    // @ts-expect-error workspace was removed in Vitest 4, but we show an error
+    workspace: 'some-options',
+  })
+  expect(stderr).toContain('The `test.workspace` option was removed in Vitest 4. Please, migrate to `test.projects` instead. See https://vitest.dev/guide/projects for examples.')
+})
diff --git a/test/config/test/projects.test.ts b/test/config/test/projects.test.ts
@@ -2,17 +2,6 @@ import { resolve } from 'pathe'
 import { expect, it } from 'vitest'
 import { runVitest } from '../../test-utils'
 
-it('correctly runs workspace tests when workspace config path is specified', async () => {
-  // TODO: remove the test in Vitest 4
-  const { stderr, stdout } = await runVitest({
-    root: 'fixtures/workspace',
-    workspace: 'nested/e2e.projects.js',
-  })
-  expect(stderr).toContain('The workspace file is deprecated and will be removed in the next major')
-  expect(stdout).toContain('1 + 1 = 2')
-  expect(stdout).not.toContain('2 + 2 = 4')
-})
-
 it('runs the workspace if there are several vitest config files', async () => {
   const { stderr, stdout } = await runVitest({
     root: 'fixtures/workspace/several-configs',
diff --git a/test/coverage-test/package.json b/test/coverage-test/package.json
@@ -3,8 +3,7 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "test": "vitest --workspace=vitest.workspace.custom.ts",
-    "vitest": "vitest"
+    "test": "vitest"
   },
   "devDependencies": {
     "@ampproject/remapping": "^2.3.0",
diff --git a/test/coverage-test/vitest.config.ts b/test/coverage-test/vitest.config.ts
diff --git a/test/coverage-test/vitest.workspace.custom.ts b/test/coverage-test/vitest.workspace.custom.ts
diff --git a/test/watch/test/config-watching.test.ts b/test/watch/test/config-watching.test.ts
