fix!: ignore --standalone when CLI filename filter is used (#8262)

AriPerkkio · web-flow · commit 013bf2cb2ca2 · 2025-07-15T16:26:09.000+02:00
diff --git a/docs/guide/cli-generated.md b/docs/guide/cli-generated.md
@@ -117,14 +117,14 @@ Enables coverage collection. Can be overridden using the `--coverage` CLI option
 - **CLI:** `--coverage.include <pattern>`
 - **Config:** [coverage.include](/config/#coverage-include)
 
-Files included in coverage as glob patterns. May be specified more than once when using multiple patterns (default: `**`)
+Files included in coverage as glob patterns. May be specified more than once when using multiple patterns. By default only files covered by tests are included.
 
 ### coverage.exclude
 
 - **CLI:** `--coverage.exclude <pattern>`
 - **Config:** [coverage.exclude](/config/#coverage-exclude)
 
-Files to be excluded in coverage. May be specified more than once when using multiple extensions (default: Visit [`coverage.exclude`](https://vitest.dev/config/#coverage-exclude))
+Files to be excluded in coverage. May be specified more than once when using multiple extensions.
 
 ### coverage.clean
 
@@ -929,4 +929,4 @@ Use `bundle` to bundle the config with esbuild or `runner` (experimental) to pro
 
 - **CLI:** `--standalone`
 
-Start Vitest without running tests. File filters will be ignored, tests will be running only on change (default: `false`)
+Start Vitest without running tests. Tests will be running only on change. This option is ignored when CLI file filters are passed. (default: `false`)
diff --git a/docs/guide/migration.md b/docs/guide/migration.md
@@ -116,6 +116,35 @@ const mock = new Spy()
 
 Note that now if you provide an arrow function, you will get [`<anonymous> is not a constructor` error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Not_a_constructor) when the mock is called.
 
+### Standalone mode with filename filter
+
+To improve user experience, Vitest will now start running the matched files when [`--standalone`](/guide/cli#standalone) is used with filename filter.
+
+```sh
+# In Vitest v3 and below this command would ignore "math.test.ts" filename filter.
+# In Vitest v4 the math.test.ts will run automatically.
+$ vitest --standalone math.test.ts
+```
+
+This allows users to create re-usable `package.json` scripts for standalone mode.
+
+::: code-group
+```json [package.json]
+{
+  "scripts": {
+    "test:dev": "vitest --standalone"
+  }
+}
+```
+```bash [CLI]
+# Start Vitest in standalone mode, without running any files on start
+$ pnpm run test:dev
+
+# Run math.test.ts immediately
+$ pnpm run test:dev math.test.ts
+```
+:::
+
 ### Deprecated APIs are Removed
 
 Vitest 4.0 removes some deprecated APIs, including:
diff --git a/packages/vitest/src/node/cli/cac.ts b/packages/vitest/src/node/cli/cac.ts
@@ -341,7 +341,7 @@ async function collect(mode: VitestRunMode, cliFilters: string[], options: CliOp
       ...normalizeCliOptions(cliFilters, options),
       watch: false,
       run: true,
-    })
+    }, undefined, undefined, cliFilters)
     if (!options.filesOnly) {
       const { testModules: tests, unhandledErrors: errors } = await ctx.collect(cliFilters.map(normalize))
 
diff --git a/packages/vitest/src/node/cli/cli-api.ts b/packages/vitest/src/node/cli/cli-api.ts
@@ -57,6 +57,7 @@ export async function startVitest(
     options,
     viteOverrides,
     vitestOptions,
+    cliFilters,
   )
 
   if (mode === 'test' && ctx.config.coverage.enabled) {
@@ -139,6 +140,7 @@ export async function prepareVitest(
   options: CliOptions = {},
   viteOverrides?: ViteUserConfig,
   vitestOptions?: VitestOptions,
+  cliFilters?: string[],
 ): Promise<Vitest> {
   process.env.TEST = 'true'
   process.env.VITEST = 'true'
@@ -148,6 +150,10 @@ export async function prepareVitest(
     options.watch = false
   }
 
+  if (options.standalone && (cliFilters?.length || 0) > 0) {
+    options.standalone = false
+  }
+
   // this shouldn't affect _application root_ that can be changed inside config
   const root = resolve(options.root || process.cwd())
 
diff --git a/packages/vitest/src/node/cli/cli-config.ts b/packages/vitest/src/node/cli/cli-config.ts
@@ -820,7 +820,7 @@ export const cliOptionsConfig: VitestCLIOptions = {
   },
   standalone: {
     description:
-      'Start Vitest without running tests. File filters will be ignored, tests will be running only on change (default: `false`)',
+      'Start Vitest without running tests. Tests will be running only on change. This option is ignored when CLI file filters are passed. (default: `false`)',
   },
   mergeReports: {
     description:
diff --git a/packages/vitest/src/node/types/config.ts b/packages/vitest/src/node/types/config.ts
@@ -912,7 +912,7 @@ export interface UserConfig extends InlineConfig {
    *
    * Vitest will only run tests if it's called programmatically or the test file changes.
    *
-   * CLI file filters will be ignored.
+   * If CLI file filters are passed, standalone mode is ignored.
    */
   standalone?: boolean
 
diff --git a/test/cli/fixtures/standalone/basic.test.ts b/test/cli/fixtures/standalone/basic.test.ts
@@ -0,0 +1,5 @@
+import { expect, test } from "vitest";
+
+test("example", () => {
+  expect(1).toBe(1);
+})
diff --git a/test/cli/fixtures/standalone/vitest.config.ts b/test/cli/fixtures/standalone/vitest.config.ts
@@ -0,0 +1,3 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({})
diff --git a/test/cli/test/standalone.test.ts b/test/cli/test/standalone.test.ts
@@ -0,0 +1,29 @@
+import { test } from 'vitest'
+import { runVitest } from '../../test-utils'
+
+test('test run is not started when --standalone', async () => {
+  const { vitest } = await runVitest({
+    root: 'fixtures/standalone',
+    standalone: true,
+    watch: true,
+  })
+
+  await vitest.waitForStdout('Vitest is running in standalone mode. Edit a test file to rerun tests.')
+  await vitest.waitForStdout('PASS  Waiting for file changes...')
+  await vitest.waitForStdout('press h to show help, press q to quit')
+})
+
+test('test run is started when --standalone and filename filter', async () => {
+  const { vitest } = await runVitest({
+    root: 'fixtures/standalone',
+    standalone: true,
+    watch: true,
+  }, ['basic.test.ts'])
+
+  await vitest.waitForStdout('✓ basic.test.ts > example')
+  await vitest.waitForStdout('Test Files  1 passed (1)')
+  await vitest.waitForStdout('Tests  1 passed (1)')
+
+  await vitest.waitForStdout('PASS  Waiting for file changes...')
+  await vitest.waitForStdout('press h to show help, press q to quit')
+})

Original file line number	Diff line number	Diff line change
`@@ -912,7 +912,7 @@ export interface UserConfig extends InlineConfig {`
`912`	`912`	`*`
`913`	`913`	`* Vitest will only run tests if it's called programmatically or the test file changes.`
`914`	`914`	`*`
`915`		`- * CLI file filters will be ignored.`
	`915`	`+ * If CLI file filters are passed, standalone mode is ignored.`
`916`	`916`	`*/`
`917`	`917`	`standalone?: boolean`
`918`	`918`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+import { defineConfig } from 'vitest/config'`
	`2`	`+`
	`3`	`+export default defineConfig({})`