feat: add "configureVitest" plugin hook (#7349)

Co-authored-by: Ari Perkkiö <[email protected]>

Author: sheremet-va

docs/.vitepress/config.ts

@@ -350,6 +350,10 @@ export default ({ mode }: { mode: string }) => {
                   },
                 ],
               },
+              {
+                text: 'Plugin API',
+                link: '/advanced/api/plugin',
+              },
               {
                 text: 'Runner API',
                 link: '/advanced/runner',

docs/advanced/api/plugin.md

@@ -0,0 +1,125 @@
+---
+title: Plugin API
+outline: deep
+---
+
+# Plugin API <Version>3.1.0</Version> {#plugin-api}
+
+::: warning
+This is an advanced API. If you just want to [run tests](/guide/), you probably don't need this. It is primarily used by library authors.
+
+This guide assumes you know how to work with [Vite plugins](https://vite.dev/guide/api-plugin.html).
+:::
+
+Vitest supports an experimental `configureVitest` [plugin](https://vite.dev/guide/api-plugin.html) hook hook since version 3.1. Any feedback regarding this API is welcome in [GitHub](https://github.com/vitest-dev/vitest/discussions/7104).
+
+::: code-group
+```ts [only vitest]
+import type { Vite, VitestPluginContext } from 'vitest/node'
+
+export function plugin(): Vite.Plugin {
+  return {
+    name: 'vitest:my-plugin',
+    configureVitest(context: VitestPluginContext) {
+      // ...
+    }
+  }
+}
+```
+```ts [vite and vitest]
+/// <reference types="vitest/config" />
+
+import type { Plugin } from 'vite'
+
+export function plugin(): Plugin {
+  return {
+    name: 'vitest:my-plugin',
+    transform() {
+      // ...
+    },
+    configureVitest(context) {
+      // ...
+    }
+  }
+}
+```
+:::
+
+::: tip TypeScript
+Vitest re-exports all Vite type-only imports via a `Vite` namespace, which you can use to keep your versions in sync. However, if you are writing a plugin for both Vite and Vitest, you can continue using the `Plugin` type from the `vite` entrypoint. Just make sure you have `vitest/config` referenced somewhere so that `configureVitest` is augmented correctly:
+
+```ts
+/// <reference types="vitest/config" />
+```
+:::
+
+Unlike [`reporter.onInit`](/advanced/api/reporters#oninit), this hooks runs early in Vitest lifecycle allowing you to make changes to configuration like `coverage` and `reporters`. A more notable change is that you can manipulate the global config from a [workspace project](/guide/workspace) if your plugin is defined in the project and not in the global config.
+
+## Context
+
+### project
+
+The current [test project](./test-project) that the plugin belongs to.
+
+::: warning Browser Mode
+Note that if you are relying on a browser feature, the `project.browser` field is not set yet. Use [`reporter.onBrowserInit`](./reporters#onbrowserinit) event instead.
+:::
+
+### vitest
+
+The global [Vitest](./vitest) instance. You can change the global configuration by directly mutating the `vitest.config` property:
+
+```ts
+vitest.config.coverage.enabled = false
+vitest.config.reporters.push([['my-reporter', {}]])
+```
+
+::: warning Config is Resolved
+Note that Vitest already resolved the config, so some types might be different from the usual user configuration. This also means that some properties will not be resolved again, like `setupFile`. If you are adding new files, make sure to resolve it first.
+
+At this point reporters are not created yet, so modifying `vitest.reporters` will have no effect because it will be overwritten. If you need to inject your own reporter, modify the config instead.
+:::
+
+### injectTestProjects
+
+```ts
+function injectTestProjects(
+  config: TestProjectConfiguration | TestProjectConfiguration[]
+): Promise<TestProject[]>
+```
+
+This methods accepts a config glob pattern, a filepath to the config or an inline configuration. It returns an array of resolved [test projects](./test-project).
+
+```ts
+// inject a single project with a custom alias
+const newProjects = await injectTestProjects({
+  // you can inherit the current project config by referencing `configFile`
+  // note that you cannot have a project with the name that already exists,
+  // so it's a good practice to define a custom name
+  configFile: project.vite.config.configFile,
+  test: {
+    name: 'my-custom-alias',
+    alias: {
+      customAlias: resolve('./custom-path.js'),
+    },
+  },
+})
+```
+
+::: warning Projects are Filtered
+Vitest filters projects during the config resolution, so if the user defined a filter, injected project might not be resolved unless it [matches the filter](./vitest#matchesprojectfilter). You can update the filter via the `vitest.config.project` option to always include your workspace project:
+
+```ts
+vitest.config.project.push('my-project-name')
+```
+
+Note that this will only affect projects injected with [`injectTestProjects`](#injecttestprojects) method.
+:::
+
+::: tip Referencing the Current Config
+If you want to keep the user configuration, you can specify the `configFile` property. All other properties will be merged with the user defined config.
+
+The project's `configFile` can be accessed in Vite's config: `project.vite.config.configFile`.
+
+Note that this will also inherit the `name` - Vitest doesn't allow multiple projects with the same name, so this will throw an error. Make sure you specified a different name. You can access the current name via the `project.name` property and all used names are available in the `vitest.projects` array.
+:::

docs/advanced/api/vitest.md

@@ -518,3 +518,13 @@ vitest.onFilterWatchedSpecification(specification =>
 ```
 
 Vitest can create different specifications for the same file depending on the `pool` or `locations` options, so do not rely on the reference. Vitest can also return cached specification from [`vitest.getModuleSpecifications`](#getmodulespecifications) - the cache is based on the `moduleId` and `pool`. Note that [`project.createSpecification`](/advanced/api/test-project#createspecification) always returns a new instance.
+
+## matchesProjectFilter <Version>3.1.0</Version> {#matchesprojectfilter}
+
+```ts
+function matchesProjectFilter(name: string): boolean
+```
+
+Check if the name matches the current [project filter](/guide/cli#project). If there is no project filter, this will always return `true`.
+
+It is not possible to programmatically change the `--project` CLI option.

packages/browser/src/node/pool.ts

@@ -169,7 +169,7 @@ export function createBrowserPool(vitest: Vitest): ProcessPool {
     async close() {
       await Promise.all([...providers].map(provider => provider.close()))
       providers.clear()
-      vitest.resolvedProjects.forEach((project) => {
+      vitest.projects.forEach((project) => {
         project.browser?.state.orchestrators.forEach((orchestrator) => {
           orchestrator.$close()
         })

packages/vitest/src/api/setup.ts

@@ -88,7 +88,7 @@ export function setup(ctx: Vitest, _server?: ViteDevServer): void {
           return ctx.getRootProject().serializedConfig
         },
         getResolvedProjectNames(): string[] {
-          return ctx.resolvedProjects.map(p => p.name)
+          return ctx.projects.map(p => p.name)
         },
         async getTransformResult(projectName: string, id, browser = false) {
           const project = ctx.getProjectByName(projectName)

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

@@ -913,7 +913,7 @@ function isPlaywrightChromiumOnly(vitest: Vitest, config: ResolvedConfig) {
   for (const instance of browser.instances) {
     const name = instance.name || (config.name ? `${config.name} (${instance.browser})` : instance.browser)
     // browser config is filtered out
-    if (!vitest._matchesProjectFilter(name)) {
+    if (!vitest.matchesProjectFilter(name)) {
       continue
     }
     if (instance.browser !== 'chromium') {

packages/vitest/src/node/core.ts

@@ -7,7 +7,7 @@ import type { SerializedCoverageConfig } from '../runtime/config'
 import type { ArgumentsType, ProvidedContext, UserConsoleLog } from '../types/general'
 import type { ProcessPool, WorkspaceSpec } from './pool'
 import type { TestSpecification } from './spec'
-import type { ResolvedConfig, UserConfig, VitestRunMode } from './types/config'
+import type { ResolvedConfig, TestProjectConfiguration, UserConfig, VitestRunMode } from './types/config'
 import type { CoverageProvider } from './types/coverage'
 import type { Reporter } from './types/reporter'
 import type { TestRunResult } from './types/tests'
@@ -98,11 +98,10 @@ export class Vitest {
   /** @internal */ _browserLastPort = defaultBrowserPort
   /** @internal */ _browserSessions = new BrowserSessions()
   /** @internal */ _options: UserConfig = {}
-  /** @internal */ reporters: Reporter[] = undefined!
+  /** @internal */ reporters: Reporter[] = []
   /** @internal */ vitenode: ViteNodeServer = undefined!
   /** @internal */ runner: ViteNodeRunner = undefined!
   /** @internal */ _testRun: TestRun = undefined!
-  /** @internal */ _projectFilters: RegExp[] = []
 
   private isFirstRun = true
   private restartsCount = 0
@@ -216,7 +215,6 @@ export class Vitest {
     this.specifications.clearCache()
     this._onUserTestsRerun = []
 
-    this._projectFilters = toArray(options.project || []).map(project => wildcardPatternToRegExp(project))
     this._vite = server
 
     const resolved = resolveConfig(this, options, server.config)
@@ -259,7 +257,7 @@ export class Vitest {
       server.watcher.on('change', async (file) => {
         file = normalize(file)
         const isConfig = file === server.config.configFile
-          || this.resolvedProjects.some(p => p.vite.config.configFile === file)
+          || this.projects.some(p => p.vite.config.configFile === file)
           || file === this._workspaceConfigPath
         if (isConfig) {
           await Promise.all(this._onRestartListeners.map(fn => fn('config')))
@@ -279,6 +277,16 @@ export class Vitest {
     const projects = await this.resolveWorkspace(cliOptions)
     this.resolvedProjects = projects
     this.projects = projects
+
+    await Promise.all(projects.flatMap((project) => {
+      const hooks = project.vite.config.getSortedPluginHooks('configureVitest')
+      return hooks.map(hook => hook({
+        project,
+        vitest: this,
+        injectTestProjects: this.injectTestProject,
+      }))
+    }))
+
     if (!this.projects.length) {
       throw new Error(`No projects matched the filter "${toArray(resolved.project).join('", "')}".`)
     }
@@ -297,6 +305,24 @@ export class Vitest {
     await Promise.all(this._onSetServer.map(fn => fn()))
   }
 
+  /**
+   * Inject new test projects into the workspace.
+   * @param config Glob, config path or a custom config options.
+   * @returns An array of new test projects. Can be empty if the name was filtered out.
+   */
+  private injectTestProject = async (config: TestProjectConfiguration | TestProjectConfiguration[]): Promise<TestProject[]> => {
+    const currentNames = new Set(this.projects.map(p => p.name))
+    const workspace = await resolveWorkspace(
+      this,
+      this._options,
+      undefined,
+      Array.isArray(config) ? config : [config],
+      currentNames,
+    )
+    this.projects.push(...workspace)
+    return workspace
+  }
+
   /**
    * Provide a value to the test context. This value will be available to all tests with `inject`.
    */
@@ -385,12 +411,15 @@ export class Vitest {
   }
 
   private async resolveWorkspace(cliOptions: UserConfig): Promise<TestProject[]> {
+    const names = new Set<string>()
+
     if (Array.isArray(this.config.workspace)) {
       return resolveWorkspace(
         this,
         cliOptions,
         undefined,
         this.config.workspace,
+        names,
       )
     }
 
@@ -406,7 +435,7 @@ export class Vitest {
       if (!project) {
         return []
       }
-      return resolveBrowserWorkspace(this, new Set(), [project])
+      return resolveBrowserWorkspace(this, new Set([project.name]), [project])
     }
 
     const workspaceModule = await this.import<{
@@ -422,6 +451,7 @@ export class Vitest {
       cliOptions,
       workspaceConfigPath,
       workspaceModule.default,
+      names,
     )
   }
 
@@ -861,11 +891,9 @@ export class Vitest {
   async changeProjectName(pattern: string): Promise<void> {
     if (pattern === '') {
       this.configOverride.project = undefined
-      this._projectFilters = []
     }
     else {
       this.configOverride.project = [pattern]
-      this._projectFilters = [wildcardPatternToRegExp(pattern)]
     }
 
     await this.vite.restart()
@@ -1096,10 +1124,10 @@ export class Vitest {
           await project._teardownGlobalSetup()
         }
 
-        const closePromises: unknown[] = this.resolvedProjects.map(w => w.close())
+        const closePromises: unknown[] = this.projects.map(w => w.close())
         // close the core workspace server only once
         // it's possible that it's not initialized at all because it's not running any tests
-        if (this.coreWorkspaceProject && !this.resolvedProjects.includes(this.coreWorkspaceProject)) {
+        if (this.coreWorkspaceProject && !this.projects.includes(this.coreWorkspaceProject)) {
           closePromises.push(this.coreWorkspaceProject.close().then(() => this._vite = undefined as any))
         }
 
@@ -1136,7 +1164,7 @@ export class Vitest {
         this.state.getProcessTimeoutCauses().forEach(cause => console.warn(cause))
 
         if (!this.pool) {
-          const runningServers = [this._vite, ...this.resolvedProjects.map(p => p._vite)].filter(Boolean).length
+          const runningServers = [this._vite, ...this.projects.map(p => p._vite)].filter(Boolean).length
 
           if (runningServers === 1) {
             console.warn('Tests closed successfully but something prevents Vite server from exiting')
@@ -1252,20 +1280,23 @@ export class Vitest {
 
   /**
    * Check if the project with a given name should be included.
-   * @internal
    */
-  _matchesProjectFilter(name: string): boolean {
+  matchesProjectFilter(name: string): boolean {
+    const projects = this._config?.project || this._options?.project
     // no filters applied, any project can be included
-    if (!this._projectFilters.length) {
+    if (!projects || !projects.length) {
       return true
     }
-    return this._projectFilters.some(filter => filter.test(name))
+    return toArray(projects).some((project) => {
+      const regexp = wildcardPatternToRegExp(project)
+      return regexp.test(name)
+    })
   }
 }
 
 function assert(condition: unknown, property: string, name: string = property): asserts condition {
   if (!condition) {
-    throw new Error(`The ${name} was not set. It means that \`vitest.${property}\` was called before the Vite server was established. Either await the Vitest promise or check that it is initialized with \`vitest.ready()\` before accessing \`vitest.${property}\`.`)
+    throw new Error(`The ${name} was not set. It means that \`vitest.${property}\` was called before the Vite server was established. Await the Vitest promise before accessing \`vitest.${property}\`.`)
   }
 }
 

packages/vitest/src/node/plugins/workspace.ts

@@ -1,6 +1,6 @@
 import type { UserConfig as ViteConfig, Plugin as VitePlugin } from 'vite'
 import type { TestProject } from '../project'
-import type { ResolvedConfig, UserWorkspaceConfig } from '../types/config'
+import type { ResolvedConfig, TestProjectInlineConfiguration } from '../types/config'
 import { existsSync, readFileSync } from 'node:fs'
 import { deepMerge } from '@vitest/utils'
 import { basename, dirname, relative, resolve } from 'pathe'
@@ -21,7 +21,7 @@ import {
 } from './utils'
 import { VitestProjectResolver } from './vitestResolver'
 
-interface WorkspaceOptions extends UserWorkspaceConfig {
+interface WorkspaceOptions extends TestProjectInlineConfiguration {
   root?: string
   workspacePath: string | number
 }
@@ -85,7 +85,7 @@ export function WorkspaceVitestPlugin(
         // if some of them match, they will later be filtered again by `resolveWorkspace`
         if (filters.length) {
           const hasProject = workspaceNames.some((name) => {
-            return project.vitest._matchesProjectFilter(name)
+            return project.vitest.matchesProjectFilter(name)
           })
           if (!hasProject) {
             throw new VitestFilteredOutProjectError()

packages/vitest/src/node/project.ts

@@ -16,8 +16,8 @@ import type { ParentProjectBrowser, ProjectBrowser } from './types/browser'
 import type {
   ResolvedConfig,
   SerializedConfig,
+  TestProjectInlineConfiguration,
   UserConfig,
-  UserWorkspaceConfig,
 } from './types/config'
 import { promises as fs, readFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
@@ -726,7 +726,7 @@ export interface SerializedTestProject {
   context: ProvidedContext
 }
 
-interface InitializeProjectOptions extends UserWorkspaceConfig {
+interface InitializeProjectOptions extends TestProjectInlineConfiguration {
   configFile: string | false
 }