feat: add experimental.preParse flag (#10070)

sheremet-va · web-flow · commit 7827363bdaee · 2026-04-07T11:49:38.000+02:00
diff --git a/docs/config/experimental.md b/docs/config/experimental.md
@@ -479,3 +479,36 @@ export default {
 If module runner is disabled, Vitest uses a native [Node.js module loader](https://nodejs.org/api/module.html#customization-hooks) to transform files to support `import.meta.vitest`, `vi.mock` and `vi.hoisted`.
 
 If you don't use these features, you can disable this to improve performance.
+
+## experimental.preParse <Version type="experimental">4.1.3</Version> {#experimental-preparse}
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Parses test specifications before running them. This applies the [`.only`](/api/test#test-only) modifier, the [`-t`](/config/testnamepattern) test name pattern, [`--tags-filter`](/guide/test-tags#syntax), [test lines](/api/advanced/test-specification#testlines), and [test IDs](/api/advanced/test-specification#testids) across all files without executing them. For example, if only a single test is marked with `.only`, Vitest will skip all other tests in all files.
+
+::: tip
+This option is recommended when using [`.only`](/api/test#test-only), the [`-t`](/config/testnamepattern) flag, or [`--tags-filter`](/guide/test-tags#syntax).
+
+Enabling it unconditionally may slow down your test runs due to the additional parsing step.
+:::
+
+::: warning
+Pre-parsing uses static analysis (AST parsing) instead of executing your test files. This means that test names, tags, and modifiers (`.only`, `.skip`, `.todo`) must be statically analyzable. Dynamic test names (e.g., names stored in variables or returned from function calls) and non-literal tags will not be resolved correctly.
+
+```ts
+// ✅ works — static string literal
+test('adds numbers', () => {})
+
+// ✅ works — static tags
+test('my test', { tags: ['unit'] }, () => {})
+
+// ❌ won't match correctly — dynamic name
+const name = getName()
+test(name, () => {})
+
+// ❌ won't match correctly — dynamic tags
+const tags = getTags()
+test('my test', { tags }, () => {})
+```
+:::
diff --git a/docs/guide/cli-generated.md b/docs/guide/cli-generated.md
@@ -963,3 +963,10 @@ Controls whether Vitest will use Node.js Loader API to process in-source or mock
 - **Config:** [experimental.vcsProvider](/config/experimental#experimental-vcsprovider)
 
 Custom provider for detecting changed files. (default: `git`)
+
+### experimental.preParse
+
+- **CLI:** `--experimental.preParse`
+- **Config:** [experimental.preParse](/config/experimental#experimental-preparse)
+
+Parse test specifications before running them. This will apply `.only` flag and test name pattern across all files without running them. (default: `false`)
diff --git a/packages/vitest/src/node/ast-collect.ts b/packages/vitest/src/node/ast-collect.ts
@@ -8,8 +8,6 @@ import {
   calculateSuiteHash,
   createTaskName,
   generateHash,
-  interpretTaskModes,
-  someTasksAreOnly,
   validateTags,
 } from '@vitest/runner/utils'
 import { unique } from '@vitest/utils/helpers'
@@ -472,17 +470,6 @@ function createFileTask(
       latestSuite.tasks.push(task)
     })
   calculateSuiteHash(file)
-  const hasOnly = someTasksAreOnly(file)
-  interpretTaskModes(
-    file,
-    config.testNamePattern,
-    undefined,
-    undefined,
-    undefined,
-    hasOnly,
-    false,
-    config.allowOnly,
-  )
   markDynamicTests(file.tasks)
   if (!file.tasks.length) {
     file.result = {
diff --git a/packages/vitest/src/node/cli/cli-config.ts b/packages/vitest/src/node/cli/cli-config.ts
@@ -920,6 +920,9 @@ export const cliOptionsConfig: VitestCLIOptions = {
         description: 'Custom provider for detecting changed files. (default: `git`)',
         subcommands: null,
       },
+      preParse: {
+        description: 'Parse test specifications before running them. This will apply `.only` flag and test name pattern across all files without running them. (default: `false`)',
+      },
     },
   },
   // disable CLI options
diff --git a/packages/vitest/src/node/core.ts b/packages/vitest/src/node/core.ts
@@ -17,7 +17,7 @@ import type { Reporter } from './types/reporter'
 import type { TestRunResult } from './types/tests'
 import type { VCSProvider } from './vcs/vcs'
 import os, { tmpdir } from 'node:os'
-import { getTasks, hasFailed, limitConcurrency } from '@vitest/runner/utils'
+import { createTagsFilter, getTasks, hasFailed, interpretTaskModes, limitConcurrency, someTasksAreOnly } from '@vitest/runner/utils'
 import { SnapshotManager } from '@vitest/snapshot/manager'
 import { deepClone, deepMerge, nanoid, toArray } from '@vitest/utils/helpers'
 import { serializeValue } from '@vitest/utils/serialize'
@@ -749,7 +749,7 @@ export class Vitest {
 
       this.filenamePattern = filters && filters?.length > 0 ? filters : undefined
       startSpan.setAttribute('vitest.start.filters', this.filenamePattern || [])
-      const specifications = await this._traces.$(
+      let specifications = await this._traces.$(
         'vitest.config.resolve_include_glob',
         async () => {
           const specifications = await this.specifications.getRelevantTestSpecifications(filters)
@@ -767,6 +767,14 @@ export class Vitest {
         },
       )
 
+      if (this.config.experimental.preParse) {
+        // This populates specification.testModule with parsed information
+        await this.experimental_parseSpecifications(specifications)
+        specifications = specifications.filter(({ testModule }) => {
+          return !testModule || testModule.task.mode !== 'skip'
+        })
+      }
+
       // if run with --changed, don't exit if no tests are found
       if (!specifications.length) {
         await this._traces.$('vitest.test_run', async () => {
@@ -1032,10 +1040,38 @@ export class Vitest {
       ? os.availableParallelism()
       : os.cpus().length)
     const limit = limitConcurrency(concurrency)
-    const promises = specifications.map(specification =>
-      limit(() => this.experimental_parseSpecification(specification)),
-    )
-    return Promise.all(promises)
+
+    // Phase 1: parse all files in parallel (without mode interpretation)
+    const results = await Promise.all(specifications.map(specification =>
+      limit(async () => {
+        const file = await astCollectTests(specification.project, specification.moduleId).catch((error) => {
+          return createFailedFileTask(specification.project, specification.moduleId, error)
+        })
+        return { file, specification }
+      }),
+    ))
+
+    const tagsFilter = this.config.tagsFilter
+      ? createTagsFilter(this.config.tagsFilter, this.config.tags)
+      : undefined
+    // Phase 2: cross-file .only resolution
+    const globalHasOnly = results.some(({ file }) => someTasksAreOnly(file))
+    for (const { file, specification } of results) {
+      const config = specification.project.config
+      interpretTaskModes(
+        file,
+        config.testNamePattern,
+        specification.testLines,
+        specification.testIds,
+        tagsFilter,
+        globalHasOnly,
+        false,
+        config.allowOnly,
+      )
+      this.state.collectFiles(specification.project, [file])
+    }
+
+    return results.map(({ file }) => this.state.getReportedEntity(file) as TestModule)
   }
 
   public async experimental_parseSpecification(specification: TestSpecification): Promise<TestModule> {
@@ -1045,6 +1081,21 @@ export class Vitest {
     const file = await astCollectTests(specification.project, specification.moduleId).catch((error) => {
       return createFailedFileTask(specification.project, specification.moduleId, error)
     })
+    const config = specification.project.config
+    const hasOnly = someTasksAreOnly(file)
+    const tagsFilter = this.config.tagsFilter
+      ? createTagsFilter(this.config.tagsFilter, this.config.tags)
+      : undefined
+    interpretTaskModes(
+      file,
+      config.testNamePattern,
+      specification.testLines,
+      specification.testIds,
+      tagsFilter,
+      hasOnly,
+      false,
+      config.allowOnly,
+    )
     // register in state, so it can be retrieved by "getReportedEntity"
     this.state.collectFiles(specification.project, [file])
     return this.state.getReportedEntity(file) as TestModule
diff --git a/packages/vitest/src/node/types/config.ts b/packages/vitest/src/node/types/config.ts
@@ -947,6 +947,12 @@ export interface InlineConfig {
      * implementation of the `VCSProvider` interface to use a different version control system.
      */
     vcsProvider?: VCSProvider | string
+
+    /**
+     * Parse test specifications before running them.
+     * This will apply `.only` flag and test name pattern across all files without running them.
+     */
+    preParse?: boolean
   }
 
   /**
diff --git a/test/cli/test/pre-parse.test.ts b/test/cli/test/pre-parse.test.ts
diff --git a/test/test-utils/index.ts b/test/test-utils/index.ts
