refactor: deprecate environmentMatchGlobs and poolMatchGlobs in favor of workspace (#6922)

Author: sheremet-va

docs/advanced/pool.md

@@ -14,7 +14,7 @@ Vitest runs tests in pools. By default, there are several pools:
 
 You can provide your own pool by specifying a file path:
 
-```ts
+```ts [vitest.config.ts]
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
@@ -27,14 +27,31 @@ export default defineConfig({
         customProperty: true,
       },
     },
-    // you can also specify pool for a subset of files
-    poolMatchGlobs: [
-      ['**/*.custom.test.ts', './my-custom-pool.ts'],
+  },
+})
+```
+
+If you need to run tests in different pools, use the [workspace](/guide/workspace) feature:
+
+```ts [vitest.config.ts]
+export default defineConfig({
+  test: {
+    workspace: [
+      {
+        extends: true,
+        test: {
+          pool: 'threads',
+        },
+      },
     ],
   },
 })
 ```
 
+::: info
+The `workspace` field was introduced in Vitest 2.2. To define a workspace in Vitest <2.2, 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:

docs/config/index.md

@@ -581,6 +581,28 @@ These options are passed down to `setup` method of current [`environment`](#envi
 - **Type:** `[string, EnvironmentName][]`
 - **Default:** `[]`
 
+::: warning
+This API was deprecated in Vitest 2.2. Use [workspace](/guide/workspace) to define different configurations instead.
+
+```ts
+export default defineConfig({
+  test: {
+    environmentMatchGlobs: [ // [!code --]
+      ['./*.jsdom.test.ts', 'jsdom'], // [!code --]
+    ], // [!code --]
+    workspace: [ // [!code ++]
+      { // [!code ++]
+        extends: true, // [!code ++]
+        test: { // [!code ++]
+          environment: 'jsdom', // [!code ++]
+        }, // [!code ++]
+      }, // [!code ++]
+    ], // [!code ++]
+  },
+})
+```
+:::
+
 Automatically assign environment based on globs. The first match will be used.
 
 For example:
@@ -606,6 +628,28 @@ export default defineConfig({
 - **Type:** `[string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]`
 - **Default:** `[]`
 
+::: warning
+This API was deprecated in Vitest 2.2. Use [workspace](/guide/workspace) to define different configurations instead:
+
+```ts
+export default defineConfig({
+  test: {
+    poolMatchGlobs: [ // [!code --]
+      ['./*.threads.test.ts', 'threads'], // [!code --]
+    ], // [!code --]
+    workspace: [ // [!code ++]
+      { // [!code ++]
+        test: { // [!code ++]
+          extends: true, // [!code ++]
+          pool: 'threads', // [!code ++]
+        }, // [!code ++]
+      }, // [!code ++]
+    ], // [!code ++]
+  },
+})
+```
+:::
+
 Automatically assign pool in which tests will run based on globs. The first match will be used.
 
 For example:
@@ -1713,7 +1757,7 @@ This is an experimental feature. Breaking changes might not follow SemVer, pleas
 - **Default:** `false`
 - **CLI:** `--browser`, `--browser.enabled=false`
 
-Run all tests inside a browser by default. Can be overridden with [`poolMatchGlobs`](#poolmatchglobs) option.
+Run all tests inside a browser by default.
 
 #### browser.name
 

docs/guide/improving-performance.md

@@ -8,7 +8,7 @@ By default Vitest runs every test file in an isolated environment based on the [
 - `forks` pool runs every test file in a separate [forked child process](https://nodejs.org/api/child_process.html#child_processforkmodulepath-args-options)
 - `vmThreads` pool runs every test file in a separate [VM context](https://nodejs.org/api/vm.html#vmcreatecontextcontextobject-options), but it uses workers for parallelism
 
-This greatly increases test times, which might not be desirable for projects that don't rely on side effects and properly cleanup their state (which is usually true for projects with `node` environment). In this case disabling isolation will improve the speed of your tests. To do that, you can provide `--no-isolate` flag to the CLI or set [`test.isolate`](/config/#isolate) property in the config to `false`. If you are using several pools at once with `poolMatchGlobs`, you can also disable isolation for a specific pool you are using.
+This greatly increases test times, which might not be desirable for projects that don't rely on side effects and properly cleanup their state (which is usually true for projects with `node` environment). In this case disabling isolation will improve the speed of your tests. To do that, you can provide `--no-isolate` flag to the CLI or set [`test.isolate`](/config/#isolate) property in the config to `false`.
 
 ::: code-group
 ```bash [CLI]

packages/vitest/src/node/config/resolveConfig.ts

@@ -532,6 +532,15 @@ export function resolveConfig(
   if (!builtinPools.includes(resolved.pool as BuiltinPool)) {
     resolved.pool = resolvePath(resolved.pool, resolved.root)
   }
+  if (resolved.poolMatchGlobs) {
+    logger.warn(
+      c.yellow(
+        `${c.inverse(
+          c.yellow(' Vitest '),
+        )} "poolMatchGlobs" is deprecated. Use "workspace" to define different configurations instead.`,
+      ),
+    )
+  }
   resolved.poolMatchGlobs = (resolved.poolMatchGlobs || []).map(
     ([glob, pool]) => {
       if (!builtinPools.includes(pool as BuiltinPool)) {
@@ -725,6 +734,15 @@ export function resolveConfig(
     ...resolved.typecheck,
   }
 
+  if (resolved.environmentMatchGlobs) {
+    logger.warn(
+      c.yellow(
+        `${c.inverse(
+          c.yellow(' Vitest '),
+        )} "environmentMatchGlobs" is deprecated. Use "workspace" to define different configurations instead.`,
+      ),
+    )
+  }
   resolved.environmentMatchGlobs = (resolved.environmentMatchGlobs || []).map(
     i => [resolve(resolved.root, i[0]), i[1]],
   )

packages/vitest/src/node/types/config.ts

@@ -314,6 +314,7 @@ export interface InlineConfig {
    *
    * Format: [glob, environment-name]
    *
+   * @deprecated use [`workspace`](https://vitest.dev/config/#environmentmatchglobs) instead
    * @default []
    * @example [
    *   // all tests in tests/dom will run in jsdom
@@ -370,6 +371,7 @@ export interface InlineConfig {
    *
    * Format: [glob, pool-name]
    *
+   * @deprecated use [`workspace`](https://vitest.dev/config/#poolmatchglobs) instead
    * @default []
    * @example [
    *   // all tests in "forks" directory will run using "poolOptions.forks" API

test/cli/fixtures/custom-pool/vitest.config.ts

@@ -2,16 +2,29 @@ import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
-    name: 'custom-pool-test',
-    pool: './pool/custom-pool.ts',
     poolOptions: {
       custom: {
         print: 'options are respected',
         array: [1, 2, 3],
       },
     },
-    poolMatchGlobs: [
-      ['**/*.threads.spec.ts', 'threads'],
-    ],
+    workspace: [
+      {
+        extends: true,
+        test: {
+          name: 'custom-pool-test',
+          pool: './pool/custom-pool.ts',
+          exclude: ['**/*.threads.spec.ts'],
+        },
+       },
+      {
+        extends: true,
+        test: {
+          name: 'threads-pool-test',
+          include: ['**/*.threads.spec.ts'],
+          pool: 'threads',
+        },
+      },
+    ]
   },
 })

test/cli/test/custom-pool.test.ts

@@ -16,7 +16,7 @@ test('can run custom pools with Vitest', async () => {
   `)
 
   expect(vitest.stdout).toContain('✓ |custom-pool-test| tests/custom-not-run.spec.ts')
-  expect(vitest.stdout).toContain('✓ |custom-pool-test| tests/custom-run.threads.spec.ts')
+  expect(vitest.stdout).toContain('✓ |threads-pool-test| tests/custom-run.threads.spec.ts')
   expect(vitest.stdout).toContain('Test Files  2 passed')
   expect(vitest.stdout).toContain('Tests  2 passed')
 })

test/config/test/pool-isolation.test.ts

@@ -31,7 +31,7 @@ describe.each(['forks', 'threads'] as const)('%s', async (pool) => {
       env: { TESTED_POOL: pool },
     })
 
-    expect(stderr).toBe('')
+    expect(stderr).toBe(deprecatedPoolMatchGlob())
     expect(exitCode).toBe(0)
   })
 
@@ -62,11 +62,15 @@ describe.each(['forks', 'threads'] as const)('%s', async (pool) => {
       env: { TESTED_POOL: pool },
     })
 
-    expect(stderr).toBe('')
+    expect(stderr).toBe(deprecatedPoolMatchGlob())
     expect(exitCode).toBe(0)
   })
 })
 
 function invertPool(pool: 'threads' | 'forks') {
   return pool === 'threads' ? 'forks' : 'threads'
 }
+
+function deprecatedPoolMatchGlob() {
+  return ' Vitest  "poolMatchGlobs" is deprecated. Use "workspace" to define different configurations instead.\n'
+}