feat: add poolOrder option

Author: sheremet-va

docs/config/index.md

@@ -772,6 +772,58 @@ Please, be aware of these issues when using this option. Vitest team cannot fix
 
 Similar as `vmThreads` pool but uses `child_process` instead of `worker_threads` via [tinypool](https://github.com/tinylibs/tinypool). Communication between tests and the main process is not as fast as with `vmThreads` pool. Process related APIs such as `process.chdir()` are available in `vmForks` pool. Please be aware that this pool has the same pitfalls listed in `vmThreads`.
 
+### poolOrder <Version>3.2.0</Version> {#poolorder}
+
+- **Type:** `number`
+- **Default:** `0`
+
+The pool group order in which this project runs its tests. If not specified, all projects run in parallel.
+
+This option only works if you have more than one project in your [workspace](/guide/workspace). If the same value is used in different projects, all those project will run together.
+
+::: details Example
+Consider this example:
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    workspace: [
+      {
+        test: {
+          name: 'slow',
+          poolOrder: 0,
+        },
+      },
+      {
+        test: {
+          name: 'fast',
+          poolOrder: 0,
+        },
+      },
+      {
+        test: {
+          name: 'flaky',
+          poolOrder: 1,
+        },
+      },
+    ],
+  },
+})
+```
+
+Tests in these projects will run in this order:
+
+```
+ 0. slow  |
+          |> running together
+ 0. fast  |
+
+ 1. flaky |> runs after slow and fast alone
+```
+:::
+
 ### poolOptions<NonProjectOption /> {#pooloptions}
 
 - **Type:** `Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>`

packages/vitest/src/node/cli/cli-config.ts

@@ -829,6 +829,7 @@ export const cliOptionsConfig: VitestCLIOptions = {
 
   // disable CLI options
   cliExclude: null,
+  poolOrder: null,
   server: null,
   setupFiles: null,
   globalSetup: null,

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

@@ -482,6 +482,8 @@ export function resolveConfig(
 
   resolved.pool ??= 'threads'
 
+  resolved.poolOrder ??= 0
+
   if (process.env.VITEST_MAX_THREADS) {
     resolved.poolOptions = {
       ...resolved.poolOptions,

packages/vitest/src/node/pool.ts

@@ -148,6 +148,7 @@ export function createPool(ctx: Vitest): ProcessPool {
       }
     }
 
+    const poolConcurrentPromises = new Map<string, Promise<ProcessPool>>()
     const customPools = new Map<string, ProcessPool>()
     async function resolveCustomPool(filepath: string) {
       if (customPools.has(filepath)) {
@@ -178,26 +179,42 @@ export function createPool(ctx: Vitest): ProcessPool {
       return poolInstance as ProcessPool
     }
 
-    const filesByPool: Record<LocalPool, TestSpecification[]> = {
-      forks: [],
-      threads: [],
-      vmThreads: [],
-      vmForks: [],
-      typescript: [],
+    function getConcurrentPool(pool: string, fn: () => Promise<ProcessPool>) {
+      if (poolConcurrentPromises.has(pool)) {
+        return poolConcurrentPromises.get(pool)!
+      }
+      const promise = fn().finally(() => {
+        poolConcurrentPromises.delete(pool)
+      })
+      poolConcurrentPromises.set(pool, promise)
+      return promise
+    }
+
+    function getCustomPool(pool: string) {
+      return getConcurrentPool(pool, () => resolveCustomPool(pool))
+    }
+
+    function getBrowserPool() {
+      return getConcurrentPool('browser', async () => {
+        const { createBrowserPool } = await import('@vitest/browser')
+        return createBrowserPool(ctx)
+      })
     }
 
+    const groupedSpecifications: TestSpecification[][] = []
+
     const factories: Record<LocalPool, () => ProcessPool> = {
       vmThreads: () => createVmThreadsPool(ctx, options),
+      vmForks: () => createVmForksPool(ctx, options),
       threads: () => createThreadsPool(ctx, options),
       forks: () => createForksPool(ctx, options),
-      vmForks: () => createVmForksPool(ctx, options),
       typescript: () => createTypecheckPool(ctx),
     }
 
     for (const spec of files) {
-      const { pool } = spec[2]
-      filesByPool[pool] ??= []
-      filesByPool[pool].push(spec)
+      const group = spec[0].config.poolOrder ?? 0
+      groupedSpecifications[group] ??= []
+      groupedSpecifications[group].push(spec)
     }
 
     const Sequencer = ctx.config.sequence.sequencer
@@ -210,35 +227,48 @@ export function createPool(ctx: Vitest): ProcessPool {
       return sequencer.sort(specs)
     }
 
-    await Promise.all(
-      Object.entries(filesByPool).map(async (entry) => {
-        const [pool, files] = entry as [Pool, TestSpecification[]]
-
-        if (!files.length) {
-          return null
-        }
-
-        const specs = await sortSpecs(files)
-
-        if (pool in factories) {
-          const factory = factories[pool]
-          pools[pool] ??= factory()
-          return pools[pool]![method](specs, invalidate)
-        }
-
-        if (pool === 'browser') {
-          pools[pool] ??= await (async () => {
-            const { createBrowserPool } = await import('@vitest/browser')
-            return createBrowserPool(ctx)
-          })()
-          return pools[pool]![method](specs, invalidate)
-        }
-
-        const poolHandler = await resolveCustomPool(pool)
-        pools[poolHandler.name] ??= poolHandler
-        return poolHandler[method](specs, invalidate)
-      }),
-    )
+    for (const specifications of groupedSpecifications) {
+      const filesByPool: Record<LocalPool, TestSpecification[]> = {
+        forks: [],
+        threads: [],
+        vmThreads: [],
+        vmForks: [],
+        typescript: [],
+      }
+
+      specifications.forEach((specification) => {
+        const pool = specification[2].pool
+        filesByPool[pool] ??= []
+        filesByPool[pool].push(specification)
+      })
+
+      await Promise.all(
+        Object.entries(filesByPool).map(async (entry) => {
+          const [pool, files] = entry as [Pool, TestSpecification[]]
+
+          if (!files.length) {
+            return null
+          }
+
+          const specs = await sortSpecs(files)
+
+          if (pool in factories) {
+            const factory = factories[pool]
+            pools[pool] ??= factory()
+            return pools[pool]![method](specs, invalidate)
+          }
+
+          if (pool === 'browser') {
+            pools.browser ??= await getBrowserPool()
+            return pools.browser[method](specs, invalidate)
+          }
+
+          const poolHandler = await getCustomPool(pool)
+          pools[poolHandler.name] ??= poolHandler
+          return poolHandler[method](specs, invalidate)
+        }),
+      )
+    }
   }
 
   return {

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

@@ -349,6 +349,16 @@ export interface InlineConfig {
    */
   poolOptions?: PoolOptions
 
+  /**
+   * The pool group order in which this project runs its tests.
+   * If not specified, all projects run in parallel.
+   *
+   * You can group tests in certain projects to run together and delay others.
+   *
+   * @default 0
+   */
+  poolOrder?: number
+
   /**
    * Maximum number or percentage of workers to run tests in. `poolOptions.{threads,vmThreads}.maxThreads`/`poolOptions.forks.maxForks` has higher priority.
    */