diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 196baeea6d69..82e433966adb 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -344,6 +344,10 @@ export default ({ mode }: { mode: string }) => { }, ], }, + { + text: 'Plugin API', + link: '/advanced/api/plugin', + }, { text: 'Runner API', link: '/advanced/runner', diff --git a/docs/advanced/api/plugin.md b/docs/advanced/api/plugin.md new file mode 100644 index 000000000000..dd01fbc0e51c --- /dev/null +++ b/docs/advanced/api/plugin.md @@ -0,0 +1,126 @@ +--- +title: Plugin API +outline: deep +--- + +# Plugin API 3.1.0 {#plugin-api} + +::: warning +This guide lists advanced APIs to run tests via a Node.js script. 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] +/// + +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 +/// +``` +::: + +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. + +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 +``` + +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 + 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 [maches the filter](./vitest#matchesprojectfilter) or has `force: true`: + +```ts +await injectTestProjects({ + // this project will always be included even + // if the `--project` filters it out + force: true, +}) +``` +::: + +::: 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. +::: diff --git a/docs/advanced/api/vitest.md b/docs/advanced/api/vitest.md index dd682a0f3d6f..15e40b3f338c 100644 --- a/docs/advanced/api/vitest.md +++ b/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 3.1.0 {#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. diff --git a/docs/guide/workspace.md b/docs/guide/workspace.md index c53e08e16ece..373cae7f3eaa 100644 --- a/docs/guide/workspace.md +++ b/docs/guide/workspace.md @@ -231,6 +231,21 @@ bun test --project e2e --project unit ``` ::: +Since Vitest 3.1, you can define a project that will always run even if you filter it out with a `--project` flag. Specify `force: true` flag when defining the project to always include it in your test run (note that this is only available in inline configs): + +```ts +export default defineWorkspace([ + { + // this project will always run even if it was filtered out + force: true, + extends: './vitest.config.ts', + test: { + name: 'unit', + }, + }, +]) +``` + ## Configuration None of the configuration options are inherited from the root-level config file, even if the workspace is defined inside that config and not in a separate `vitest.workspace` file. You can create a shared config file and merge it with the project config yourself: diff --git a/packages/vitest/src/node/config/resolveConfig.ts b/packages/vitest/src/node/config/resolveConfig.ts index 804f16591e4d..4c319cc25bcd 100644 --- a/packages/vitest/src/node/config/resolveConfig.ts +++ b/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') { diff --git a/packages/vitest/src/node/core.ts b/packages/vitest/src/node/core.ts index ee3dd86610ce..1a1b56f358fe 100644 --- a/packages/vitest/src/node/core.ts +++ b/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,7 +98,7 @@ 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! @@ -279,6 +279,12 @@ 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 +303,26 @@ 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 New test project or `undefined` if it was filtered out. + */ + private injectTestProject = async (config: TestProjectConfiguration | TestProjectConfiguration[]): Promise => { + // TODO: test that it errors when the project is already in the workspace + 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.resolvedProjects.push(...workspace) + 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 { + const names = new Set() + 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, ) } @@ -1252,9 +1282,8 @@ export class Vitest { /** * Check if the project with a given name should be included. - * @internal */ - _matchesProjectFilter(name: string): boolean { + matchesProjectFilter(name: string): boolean { // no filters applied, any project can be included if (!this._projectFilters.length) { return true diff --git a/packages/vitest/src/node/plugins/workspace.ts b/packages/vitest/src/node/plugins/workspace.ts index 0f3594f4cda0..68638ac08792 100644 --- a/packages/vitest/src/node/plugins/workspace.ts +++ b/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' @@ -22,7 +22,7 @@ import { } from './utils' import { VitestProjectResolver } from './vitestResolver' -interface WorkspaceOptions extends UserWorkspaceConfig { +interface WorkspaceOptions extends TestProjectInlineConfiguration { root?: string workspacePath: string | number } @@ -84,9 +84,11 @@ export function WorkspaceVitestPlugin( // if there is `--project=...` filter, check if any of the potential projects match // if projects don't match, we ignore the test project altogether // if some of them match, they will later be filtered again by `resolveWorkspace` - if (filters.length) { + // ignore if `{ force: true }` is set + // TODO: test for force + if (!options.force && filters.length) { const hasProject = workspaceNames.some((name) => { - return project.vitest._matchesProjectFilter(name) + return project.vitest.matchesProjectFilter(name) }) if (!hasProject) { throw new VitestFilteredOutProjectError() diff --git a/packages/vitest/src/node/project.ts b/packages/vitest/src/node/project.ts index eec80e229e71..eb4bc39b906d 100644 --- a/packages/vitest/src/node/project.ts +++ b/packages/vitest/src/node/project.ts @@ -13,8 +13,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' @@ -722,7 +722,7 @@ export interface SerializedTestProject { context: ProvidedContext } -interface InitializeProjectOptions extends UserWorkspaceConfig { +interface InitializeProjectOptions extends TestProjectInlineConfiguration { configFile: string | false } diff --git a/packages/vitest/src/node/types/config.ts b/packages/vitest/src/node/types/config.ts index b6a7a65eef89..dfcc08188282 100644 --- a/packages/vitest/src/node/types/config.ts +++ b/packages/vitest/src/node/types/config.ts @@ -1123,14 +1123,24 @@ export type UserProjectConfigExport = | Promise | UserProjectConfigFn -export type TestProjectConfiguration = string | (UserProjectConfigExport & { +export type TestProjectInlineConfiguration = (UserWorkspaceConfig & { /** * Relative path to the extendable config. All other options will be merged with this config. * If `true`, the project will inherit all options from the root config. * @example '../vite.config.ts' */ extends?: string | true + /** + * Always include this project in the test run, even if it's filtered out by the `--project` option. + */ + force?: true }) +export type TestProjectConfiguration = + string + | TestProjectInlineConfiguration + | Promise + | UserProjectConfigFn + /** @deprecated use `TestProjectConfiguration` instead */ export type WorkspaceProjectConfiguration = TestProjectConfiguration diff --git a/packages/vitest/src/node/types/plugin.ts b/packages/vitest/src/node/types/plugin.ts new file mode 100644 index 000000000000..012084d8417c --- /dev/null +++ b/packages/vitest/src/node/types/plugin.ts @@ -0,0 +1,9 @@ +import type { Vitest } from '../core' +import type { TestProject } from '../project' +import type { TestProjectConfiguration } from './config' + +export interface VitestPluginContext { + vitest: Vitest + project: TestProject + injectTestProjects: (config: TestProjectConfiguration | TestProjectConfiguration[]) => Promise +} diff --git a/packages/vitest/src/node/types/vite.ts b/packages/vitest/src/node/types/vite.ts index 60d9b7764565..3de960bceaa4 100644 --- a/packages/vitest/src/node/types/vite.ts +++ b/packages/vitest/src/node/types/vite.ts @@ -1,4 +1,8 @@ +/* eslint-disable unused-imports/no-unused-vars */ + +import type { HookHandler } from 'vite' import type { InlineConfig } from './config' +import type { VitestPluginContext } from './plugin' type VitestInlineConfig = InlineConfig @@ -9,6 +13,10 @@ declare module 'vite' { */ test?: VitestInlineConfig } + + interface Plugin { + configureVitest?: HookHandler<(context: VitestPluginContext) => void> + } } export {} diff --git a/packages/vitest/src/node/workspace/resolveWorkspace.ts b/packages/vitest/src/node/workspace/resolveWorkspace.ts index d36d611ab091..0bb7a98aa1f1 100644 --- a/packages/vitest/src/node/workspace/resolveWorkspace.ts +++ b/packages/vitest/src/node/workspace/resolveWorkspace.ts @@ -19,6 +19,7 @@ export async function resolveWorkspace( cliOptions: UserConfig, workspaceConfigPath: string | undefined, workspaceDefinition: TestProjectConfiguration[], + names: Set, ): Promise { const { configFiles, projectConfigs, nonConfigDirectories } = await resolveTestProjectConfigs( vitest, @@ -114,7 +115,6 @@ export async function resolveWorkspace( } const resolvedProjectsPromises = await Promise.allSettled(projectPromises) - const names = new Set() const errors: Error[] = [] const resolvedProjects: TestProject[] = [] @@ -201,11 +201,11 @@ export async function resolveBrowserWorkspace( } const originalName = project.config.name // if original name is in the --project=name filter, keep all instances - const filteredInstances = !vitest._projectFilters.length || vitest._matchesProjectFilter(originalName) + const filteredInstances = !vitest._projectFilters.length || vitest.matchesProjectFilter(originalName) ? instances : instances.filter((instance) => { const newName = instance.name! // name is set in "workspace" plugin - return vitest._matchesProjectFilter(newName) + return vitest.matchesProjectFilter(newName) }) // every project was filtered out @@ -462,7 +462,7 @@ export function getDefaultTestProject(vitest: Vitest): TestProject | null { } // check for the project name and browser names const hasProjects = getPotentialProjectNames(project).some(p => - vitest._matchesProjectFilter(p), + vitest.matchesProjectFilter(p), ) if (hasProjects) { return project diff --git a/packages/vitest/src/public/config.ts b/packages/vitest/src/public/config.ts index fd906108cb68..6b7374d5219f 100644 --- a/packages/vitest/src/public/config.ts +++ b/packages/vitest/src/public/config.ts @@ -1,6 +1,13 @@ import type { ConfigEnv, UserConfig as ViteUserConfig } from 'vite' -import type { TestProjectConfiguration, UserProjectConfigExport, UserProjectConfigFn, UserWorkspaceConfig, WorkspaceProjectConfiguration } from '../node/types/config' +import type { + TestProjectConfiguration, + TestProjectInlineConfiguration, + UserProjectConfigExport, + UserProjectConfigFn, + UserWorkspaceConfig, + WorkspaceProjectConfiguration, +} from '../node/types/config' import '../node/types/vite' export { extraInlineDeps } from '../constants' @@ -20,7 +27,14 @@ export type { ConfigEnv, ViteUserConfig } * @deprecated Use `ViteUserConfig` instead */ export type UserConfig = ViteUserConfig -export type { TestProjectConfiguration, UserProjectConfigExport, UserProjectConfigFn, UserWorkspaceConfig, WorkspaceProjectConfiguration } +export type { + TestProjectConfiguration, + TestProjectInlineConfiguration, + UserProjectConfigExport, + UserProjectConfigFn, + UserWorkspaceConfig, + WorkspaceProjectConfiguration, +} export type UserConfigFnObject = (env: ConfigEnv) => ViteUserConfig export type UserConfigFnPromise = (env: ConfigEnv) => Promise export type UserConfigFn = ( diff --git a/packages/vitest/src/public/node.ts b/packages/vitest/src/public/node.ts index 416128d66aaf..98a65403c507 100644 --- a/packages/vitest/src/public/node.ts +++ b/packages/vitest/src/public/node.ts @@ -121,6 +121,7 @@ export type { ResolvedCoverageOptions, } from '../node/types/coverage' +export type { VitestPluginContext } from '../node/types/plugin' export type { TestRunResult } from '../node/types/tests' /** * @deprecated Use `TestModule` instead