fix: run gutter tests with the most specific config when several configs claim the same file

When a shared base config (e.g. vitest.config.base.ts) matches the
extension's configGlob, it gets its own Vitest instance that claims the
same test files as the package-level configs merging it. The editor
gutter "Run Test" button then executed tests with the base config,
which lacks the merged test options (tags, env, ...), failing with
errors like 'The Vitest config does't define any "tags"'.

Two changes:

1. testTree: file items now accumulate the tags of every config that
   claims them (folder items already did this). Previously a file item
   only carried the tag of the first config that resolved it, so that
   config's profile was the only one VS Code could ever pick.

2. extension: run/debug/coverage profiles are registered for all
   discovered configs upfront - deepest config first - before any
   Vitest process spawns. When several profiles can run the same test
   item, VS Code invokes the first-registered one, so the most specific
   config becomes the effective default. Config resolution order is
   unchanged; profiles for configs that never resolve (claimed by a
   workspace config, disabled, or failed) are disposed after resolution.

Verified with a new e2e regression test: a gutter run on a test file
claimed by both a root base config and a package-level config must
execute under the package-level config.

Fixes #799

Author: bennycode

packages/extension/src/extension.ts

@@ -1,5 +1,6 @@
 import type { VitestAPI } from './api'
 import type { VitestProcessAPI } from './apiProcess'
+import type { VitestPackage } from './spawn/pkg'
 import { basename, normalize, relative } from 'pathe'
 import * as vscode from 'vscode'
 import { version } from '../../../package.json'
@@ -128,6 +129,7 @@ class VitestExtension {
 
     const previousRunProfiles = this.runProfiles
     this.runProfiles = new Map()
+    const resolvedConfigs = new Set<string>()
 
     try {
       await this.api?.dispose()
@@ -140,6 +142,16 @@ class VitestExtension {
         profile.dispose()
       }
 
+      // Register run profiles for all discovered configs upfront, most specific
+      // config first — before any Vitest process is spawned (#799). When several
+      // profiles can run the same test item, VS Code invokes the profile that was
+      // registered first, so this makes e.g. `packages/foo/vitest.config.ts` win
+      // over a root `vitest.config.base.ts` that also claims the same test files.
+      // `setupProcessAPI` binds the real run handlers to these profiles as each
+      // config resolves; profiles for configs that never resolve (e.g. claimed by
+      // a workspace config) are disposed below.
+      this.registerRunProfiles([...workspaces, ...configs])
+
       this.api = await resolveVitestAPI(
         workspaces,
         configs,
@@ -149,6 +161,7 @@ class VitestExtension {
             return
           }
 
+          resolvedConfigs.add(vitest.id)
           this.testTree.watchTestFilesInWorkspace(vitest, files)
           this.setupProcessAPI(vitest)
 
@@ -165,6 +178,16 @@ class VitestExtension {
       return
     } finally {
       this.testController.items.delete(this.loadingTestItem.id)
+
+      // dispose profiles whose configs never resolved — configs claimed by a
+      // workspace config, disabled configs, or failed/cancelled resolution
+      for (const [key, profile] of this.runProfiles) {
+        const configId = key.slice(0, key.lastIndexOf(':'))
+        if (!resolvedConfigs.has(configId)) {
+          profile.dispose()
+          this.runProfiles.delete(key)
+        }
+      }
     }
 
     this.api.processes.forEach((process) => {
@@ -193,6 +216,43 @@ class VitestExtension {
     })
   }
 
+  private registerRunProfiles(packages: VitestPackage[]) {
+    // deepest config first, so the most specific config becomes the profile
+    // VS Code picks when several configs claim the same test file (#799)
+    const sortedPackages = [...packages].sort((a, b) => {
+      return normalize(b.id).split('/').length - normalize(a.id).split('/').length
+    })
+
+    const kinds: [string, vscode.TestRunProfileKind, boolean][] = [
+      ['run', vscode.TestRunProfileKind.Run, true],
+      // continuous debugging and coverage are not supported
+      ['debug', vscode.TestRunProfileKind.Debug, false],
+      ['coverage', vscode.TestRunProfileKind.Coverage, false],
+    ]
+
+    for (const pkg of sortedPackages) {
+      const id = normalize(pkg.id)
+      const tag = new vscode.TestTag(pkg.prefix)
+      for (const [name, kind, supportsContinuousRun] of kinds) {
+        const key = `${id}:${name}`
+        if (this.runProfiles.has(key)) {
+          continue
+        }
+        const profile = this.testController.createRunProfile(
+          pkg.prefix,
+          kind,
+          () => {
+            log.error('Run handler is not defined')
+          },
+          true,
+          tag,
+          supportsContinuousRun,
+        )
+        this.runProfiles.set(key, profile)
+      }
+    }
+  }
+
   private setupProcessAPI(vitest: VitestProcessAPI) {
     // Register collection listener so test tree gets notified when tests are collected
     vitest.onCollected((file) => {

packages/extension/src/testTree.ts

@@ -146,7 +146,12 @@ export class TestTree extends vscode.Disposable {
     const normalizedFile = normalize(file)
     const fileId = `${normalizedFile}${project}`
     const cached = this.fileItems.get(fileId)
-    if (cached) return cached
+    if (cached) {
+      // another config also claims this file — add its tag so the config's
+      // run profiles can run this item too (#799)
+      if (!cached.tags.includes(api.tag)) cached.tags = [...cached.tags, api.tag]
+      return cached
+    }
 
     const fileUri = vscode.Uri.file(resolve(file))
     const parentItem = this.getOrCreateFolderTestItem(api, dirname(file))

pnpm-lock.yaml

@@ -0,0 +1,25 @@
+# Shared base config (#799)
+
+Regression workspace for [vitest-dev/vscode#799](https://github.com/vitest-dev/vscode/issues/799):
+a shared base config (`vitest.config.base.ts`) whose name matches the extension's
+`configGlob`, so the extension discovers it as a runnable config. Rooted at the
+workspace root with the default `include`, it claims the same test files as the
+package-level config that merges it.
+
+```
+vitest.config.base.ts                    "base"  — CONFIG_NAME=base
+packages/foo/vitest.config.ts            "leaf"  — mergeConfig(base) + CONFIG_NAME=leaf
+packages/foo/test/which-config.test.ts   passes ONLY under the leaf config
+```
+
+The test asserts `process.env.CONFIG_NAME === 'leaf'`, so the run result alone
+tells you which config executed it.
+
+When several run profiles can run the same test item, VS Code invokes the
+profile that was **registered first**. The extension therefore registers
+profiles for the most specific (deepest) configs first, so the editor gutter
+"Run Test" button executes this workspace's tests with
+`packages/foo/vitest.config.ts` — not the shared base config, which does not
+carry the merged test options (`tags`, `env`, …).
+
+Covered by `test/e2e/shared-base-config.test.ts`.

samples/shared-base-config/README.md

@@ -0,0 +1,12 @@
+{
+  "name": "@vitest/vscode-sample-shared-base-config",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "catalog:latest"
+  }
+}

samples/shared-base-config/package.json

@@ -0,0 +1,9 @@
+import { expect, it } from 'vitest'
+
+// Discriminator test: passes ONLY when run through packages/foo/vitest.config.ts
+// (the "leaf" config, CONFIG_NAME=leaf). Fails when run through the root
+// vitest.config.base.ts, which the extension also discovers and which claims
+// this file too (vitest-dev/vscode#799).
+it('runs with the leaf config', () => {
+  expect(process.env.CONFIG_NAME).toBe('leaf')
+})

samples/shared-base-config/packages/foo/test/which-config.test.ts

@@ -0,0 +1,13 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+import baseConfig from '../../vitest.config.base'
+
+export default mergeConfig(
+  baseConfig,
+  defineConfig({
+    test: {
+      env: {
+        CONFIG_NAME: 'leaf',
+      },
+    },
+  }),
+)

samples/shared-base-config/packages/foo/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config'
+
+// Shared base config — NOT meant to be run directly, only merged into
+// package-level configs. Its name intentionally matches the extension's
+// configGlob so the extension discovers it as a runnable config, which
+// reproduces vitest-dev/vscode#799.
+export default defineConfig({
+  test: {
+    env: {
+      CONFIG_NAME: 'base',
+    },
+  },
+})

samples/shared-base-config/vitest.config.base.ts

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs'
+import type { Page } from '@playwright/test'
+import { expect } from '@playwright/test'
+import { beforeAll, vi } from 'vitest'
+import { test } from './utils/helper'
+
+// Regression test for vitest-dev/vscode#799.
+//
+// The workspace `samples/shared-base-config` contains a shared base config
+// (`vitest.config.base.ts`) that matches the extension's configGlob and claims
+// the same test file as the package-level config that merges it. When several
+// run profiles can run the same test item, VS Code invokes the profile that
+// was registered FIRST — so the extension must register the most specific
+// (deepest) config's profiles first. The test file passes ONLY under the
+// package-level "leaf" config (it asserts CONFIG_NAME === 'leaf'), so a
+// passing run proves the gutter button used the right config.
+
+// Vitest extension doesn't work with CI flag
+beforeAll(() => {
+  delete process.env.CI
+  delete process.env.GITHUB_ACTIONS
+})
+
+async function openFileViaQuickOpen(page: Page, fileName: string) {
+  // click the result row instead of pressing Enter — Enter races the async
+  // population of the quick-open result list
+  await page.keyboard.press('ControlOrMeta+P')
+  await page.keyboard.type(fileName)
+  const row = page.locator('.quick-input-widget .monaco-list-row', { hasText: fileName }).first()
+  await row.waitFor({ state: 'visible', timeout: 30_000 })
+  await row.click()
+  await page
+    .locator('.tabs-container .tab', { hasText: fileName })
+    .first()
+    .waitFor({ state: 'visible', timeout: 30_000 })
+}
+
+test('gutter run uses the most specific config, not the shared base config', async ({
+  launch,
+  logPath,
+}) => {
+  const { page, tester } = await launch({
+    workspacePath: './samples/shared-base-config',
+  })
+
+  // wait until BOTH discovered configs are resolved — clicking earlier could
+  // pass spuriously with only the leaf config registered
+  await vi.waitUntil(
+    () => {
+      try {
+        const log = readFileSync(logPath, 'utf-8')
+        return (
+          log.includes('Watching vitest.config.base.ts') &&
+          log.includes('Watching packages/foo/vitest.config.ts')
+        )
+      } catch {
+        return false
+      }
+    },
+    { timeout: 60_000 },
+  )
+
+  await openFileViaQuickOpen(page, 'which-config.test.ts')
+
+  // the run glyph appears in the editor margin once tests are discovered
+  const glyph = page.locator('.glyph-margin-widgets .testing-run-glyph').first()
+  await glyph.waitFor({ state: 'visible', timeout: 60_000 })
+  await glyph.click()
+
+  // the test passes only under packages/foo/vitest.config.ts; if the shared
+  // base config ran it instead, the summary shows 0/1
+  await expect(tester.tree.getResultsLocator()).toHaveText('1/1', { timeout: 30_000 })
+})