import { DevEnvironment, IndexHtmlTransformContext, IndexHtmlTransformResult, ViteDevServer, UserConfig as UserConfig$1, Plugin, ResolvedConfig as ResolvedConfig$1, TransformResult as TransformResult$1, InlineConfig as InlineConfig$1, DepOptimizationConfig, ServerOptions, ConfigEnv, AliasOptions } from 'vite';
import { aU as TaskMeta, U as UserConsoleLog, O as Suite, a as File, bi as SerializableRetry, T as TestError, g as TestAnnotation, h as TestArtifact, b0 as TestBenchmark, aJ as SerializedError, a0 as ImportDuration, m as Test, A as Awaitable, Y as CancelReason, P as ParsedStack, bj as BrowserTraceViewMode, a5 as BaselineData, o as ProvidedContext, b as SerializedConfig, bk as Arrayable, a2 as AfterSuiteRunMeta, aO as SnapshotStateOptions, aP as SnapshotSummary, aM as SnapshotResult, X as Task, bl as AsyncLeak, j as TaskResultPack, F as FileSpecification, l as SerializedRootConfig, L as LabelColor, c as SerializedDiffOptions, bg as SequenceSetupFiles, bf as SequenceHooks, bm as PrettyFormatOptions, C as Config, e as TestTagDefinition } from './config.d.BxjInJat.js';
import { Writable } from 'node:stream';
import { S as SerializedTestSpecification, B as BrowserTesterOptions, c as SourceModuleDiagnostic } from './browser.d.3cffPS1V.js';
import * as chai from 'chai';
import { happyDomTypes, jsdomTypes } from 'vitest/optional-types.js';
import { a as ContextTestEnvironment, b as WorkerExecuteContext, c as WorkerTestEnvironment } from './worker.d.Bt2A2mmi.js';
import { O as OTELCarrier } from './rpc.d.BPFHl-HE.js';
import { MockedModule } from '@vitest/mocker';
import { S as StackTraceParserOptions, a as RuntimeCoverageProviderModule } from './source-map.d.BLHtC2OB.js';
import { CDPSession, BrowserCommands, MarkOptions } from 'vitest/browser';
import path from 'node:path';
import { Console } from 'node:console';
import { writeFile } from 'node:fs/promises';
import { Stats } from 'node:fs';
type ChaiConfig = Omit, "useProxy" | "proxyExcludedKeys" | "deepEqual">;
type HappyDOMOptions = Omit[0]>, "console">;
type JSDOMOptions = ConstructorOptionsOverride & Omit;
interface ConstructorOptionsOverride {
/**
* The html content for the test.
*
* @default ''
*/
html?: string | ArrayBufferLike;
/**
* userAgent affects the value read from navigator.userAgent, as well as the User-Agent header sent while fetching subresources.
*
* @default `Mozilla/5.0 (${process.platform}) AppleWebKit/537.36 (KHTML, like Gecko) jsdom/${jsdomVersion}`
*/
userAgent?: string;
/**
* url sets the value returned by window.location, document.URL, and document.documentURI,
* and affects things like resolution of relative URLs within the document
* and the same-origin restrictions and referrer used while fetching subresources.
*
* @default 'http://localhost:3000'.
*/
url?: string;
/**
* Enable console?
*
* @default false
*/
console?: boolean;
/**
* jsdom does not have the capability to render visual content, and will act like a headless browser by default.
* It provides hints to web pages through APIs such as document.hidden that their content is not visible.
*
* When the `pretendToBeVisual` option is set to `true`, jsdom will pretend that it is rendering and displaying
* content.
*
* @default true
*/
pretendToBeVisual?: boolean;
/**
* Enable CookieJar
*
* @default false
*/
cookieJar?: boolean;
resources?: "usable";
}
declare class ReportedTaskImplementation {
/**
* The project associated with the test or suite.
*/
readonly project: TestProject;
/**
* Unique identifier.
* This ID is deterministic and will be the same for the same test across multiple runs.
* The ID is based on the project name, module url and test order.
*/
readonly id: string;
/**
* Location in the module where the test or suite is defined.
*/
readonly location: {
line: number;
column: number;
} | undefined;
/**
* Checks if the test did not fail the suite.
* If the test is not finished yet or was skipped, it will return `true`.
*/
ok(): boolean;
/**
* Custom metadata that was attached to the test during its execution.
*/
meta(): TaskMeta;
/**
* Console logs recorded during the test execution.
*/
logs(): ReadonlyArray;
}
declare class TestCase extends ReportedTaskImplementation {
#private;
readonly type = "test";
/**
* Direct reference to the test module where the test or suite is defined.
*/
readonly module: TestModule;
/**
* Name of the test.
*/
readonly name: string;
/**
* Options that the test was initiated with.
*/
readonly options: TaskOptions;
/**
* Parent suite. If the test was called directly inside the module, the parent will be the module itself.
*/
readonly parent: TestSuite | TestModule;
/**
* Tags associated with the test.
*/
readonly tags: string[];
/**
* Full name of the test including all parent suites separated with `>`.
*/
get fullName(): string;
/**
* Test results.
* - **pending**: Test was collected, but didn't finish running yet.
* - **passed**: Test passed successfully
* - **failed**: Test failed to execute
* - **skipped**: Test was skipped during collection or dynamically with `ctx.skip()`.
*/
result(): TestResult;
/**
* Test annotations added via the `task.annotate` API during the test execution.
*/
annotations(): ReadonlyArray;
/**
* @experimental
*
* Test artifacts recorded via the `recordArtifact` API during the test execution.
*/
artifacts(): ReadonlyArray;
/**
* @experimental
*
* A list of benchmarks performed during the test.
*/
benchmarks(): ReadonlyArray;
/**
* Useful information about the test like duration, memory usage, etc.
* Diagnostic is only available after the test has finished.
*/
diagnostic(): TestDiagnostic | undefined;
/**
* Returns a new test specification that can be used to filter or run this specific test case.
*/
toTestSpecification(): TestSpecification;
}
declare class TestCollection {
#private;
constructor(task: Suite | File, project: TestProject);
/**
* Returns the test or suite at a specific index.
*/
at(index: number): TestCase | TestSuite | undefined;
/**
* The number of tests and suites in the collection.
*/
get size(): number;
/**
* Returns the collection in array form for easier manipulation.
*/
array(): (TestCase | TestSuite)[];
/**
* Filters all tests that are part of this collection and its children.
*/
allTests(state?: TestState): Generator;
/**
* Filters only the tests that are part of this collection.
*/
tests(state?: TestState): Generator;
/**
* Filters only the suites that are part of this collection.
*/
suites(): Generator;
/**
* Filters all suites that are part of this collection and its children.
*/
allSuites(): Generator;
[Symbol.iterator](): Generator;
}
type ReportedHookContext = {
readonly name: "beforeAll" | "afterAll";
readonly entity: TestSuite | TestModule;
} | {
readonly name: "beforeEach" | "afterEach";
readonly entity: TestCase;
};
declare abstract class SuiteImplementation extends ReportedTaskImplementation {
/**
* Collection of suites and tests that are part of this suite.
*/
readonly children: TestCollection;
/**
* Errors that happened outside of the test run during collection, like syntax errors.
*/
errors(): SerializedError[];
}
declare class TestSuite extends SuiteImplementation {
#private;
readonly type = "suite";
/**
* Name of the test or the suite.
*/
readonly name: string;
/**
* Direct reference to the test module where the test or suite is defined.
*/
readonly module: TestModule;
/**
* Parent suite. If suite was called directly inside the module, the parent will be the module itself.
*/
readonly parent: TestSuite | TestModule;
/**
* Options that suite was initiated with.
*/
readonly options: TaskOptions;
/**
* Checks if the suite has any failed tests.
* This will also return `false` if suite failed during collection.
*/
ok: () => boolean;
/**
* The meta information attached to the suite during its collection or execution.
*/
meta: () => TaskMeta;
/**
* Checks the running state of the suite.
*/
state(): TestSuiteState;
/**
* Returns a new test specification that can be used to filter or run this specific test suite.
*/
toTestSpecification(): TestSpecification;
/**
* Full name of the suite including all parent suites separated with `>`.
*/
get fullName(): string;
}
declare class TestModule extends SuiteImplementation {
readonly location: undefined;
readonly type = "module";
/**
* The Vite environment that processes files on the server.
*
* Can be empty if test module did not run yet.
*/
readonly viteEnvironment: DevEnvironment | undefined;
/**
* This is usually an absolute UNIX file path.
* It can be a virtual ID if the file is not on the disk.
* This value corresponds to the ID in the Vite's module graph.
*/
readonly moduleId: string;
/**
* Module id relative to the project. This is the same as `task.name`.
*/
readonly relativeModuleId: string;
/**
* Returns a new test specification that can be used to filter or run this specific test module.
*/
toTestSpecification(testCases?: TestCase[]): TestSpecification;
/**
* Checks the running state of the test file.
*/
state(): TestModuleState;
/**
* Checks if the module has any failed tests.
* This will also return `false` if module failed during collection.
*/
ok: () => boolean;
/**
* The meta information attached to the module during its collection or execution.
*/
meta: () => TaskMeta;
/**
* Useful information about the module like duration, memory usage, etc.
* If the module was not executed yet, all diagnostic values will return `0`.
*/
diagnostic(): ModuleDiagnostic;
}
interface TaskOptions {
readonly each: boolean | undefined;
readonly fails: boolean | undefined;
readonly concurrent: boolean | undefined;
readonly shuffle: boolean | undefined;
readonly retry: SerializableRetry | undefined;
readonly repeats: number | undefined;
readonly tags: string[] | undefined;
/**
* Only tests have a `timeout` option.
*/
readonly timeout: number | undefined;
readonly mode: "run" | "only" | "skip" | "todo";
}
type TestSuiteState = "skipped" | "pending" | "failed" | "passed";
type TestModuleState = TestSuiteState | "queued";
type TestState = TestResult["state"];
type TestResult = TestResultPassed | TestResultFailed | TestResultSkipped | TestResultPending;
interface TestResultPending {
/**
* The test was collected, but didn't finish running yet.
*/
readonly state: "pending";
/**
* Pending tests have no errors.
*/
readonly errors: undefined;
}
interface TestResultPassed {
/**
* The test passed successfully.
*/
readonly state: "passed";
/**
* Errors that were thrown during the test execution.
*
* **Note**: If test was retried successfully, errors will still be reported.
*/
readonly errors: ReadonlyArray | undefined;
}
interface TestResultFailed {
/**
* The test failed to execute.
*/
readonly state: "failed";
/**
* Errors that were thrown during the test execution.
*/
readonly errors: ReadonlyArray;
}
interface TestResultSkipped {
/**
* The test was skipped with `only` (on another test), `skip` or `todo` flag.
* You can see which one was used in the `options.mode` option.
*/
readonly state: "skipped";
/**
* Skipped tests have no errors.
*/
readonly errors: undefined;
/**
* A custom note passed down to `ctx.skip(note)`.
*/
readonly note: string | undefined;
}
interface TestDiagnostic {
/**
* If the duration of the test is above `slowTestThreshold`.
*/
readonly slow: boolean;
/**
* The amount of memory used by the test in bytes.
* This value is only available if the test was executed with `logHeapUsage` flag.
*/
readonly heap: number | undefined;
/**
* The time it takes to execute the test in ms.
*/
readonly duration: number;
/**
* The time in ms when the test started.
*/
readonly startTime: number;
/**
* The amount of times the test was retried.
*/
readonly retryCount: number;
/**
* The amount of times the test was repeated as configured by `repeats` option.
* This value can be lower if the test failed during the repeat and no `retry` is configured.
*/
readonly repeatCount: number;
/**
* If test passed on a second retry.
*/
readonly flaky: boolean;
}
interface ModuleDiagnostic {
/**
* The time it takes to import and initiate an environment.
*/
readonly environmentSetupDuration: number;
/**
* The time it takes Vitest to setup test harness (runner, mocks, etc.).
*/
readonly prepareDuration: number;
/**
* The time it takes to import the test module.
* This includes importing everything in the module and executing suite callbacks.
*/
readonly collectDuration: number;
/**
* The time it takes to import the setup module.
*/
readonly setupDuration: number;
/**
* Accumulated duration of all tests and hooks in the module.
*/
readonly duration: number;
/**
* The amount of memory used by the test module in bytes.
* This value is only available if the test was executed with `logHeapUsage` flag.
*/
readonly heap: number | undefined;
/**
* The time spent importing every non-externalized dependency that Vitest has processed.
*/
readonly importDurations: Record;
/**
* The id of the worker that ran this file. This value cannot be higher than `maxWorkers`.
* If file did not run yet, this will be 0.
*
* **Warning**: Node.js tests and browser tests run in different pools and do not share `concurrencyId`.
* It is possible to have multiple modules with the same `concurrencyId` because of that.
* Use `project.isBrowserEnabled()` to distinguish the concurrency.
* @since 5.0.0
*/
readonly concurrencyId: number;
/**
* Incremental number of the worker that ran this file. This number increases with each worker.
* If file did not run yet, this will be 0.
*
* **Warning**: Node.js tests and browser tests run in different pools and do not share `workerId`.
* It is possible to have multiple modules with the same `workerId` because of that.
* Use `project.isBrowserEnabled()` to distinguish the concurrency.
* @since 5.0.0
*/
readonly workerId: number;
}
declare function experimental_getRunnerTask(entity: TestCase): Test;
declare function experimental_getRunnerTask(entity: TestSuite): Suite;
declare function experimental_getRunnerTask(entity: TestModule): File;
declare function experimental_getRunnerTask(entity: TestCase | TestSuite | TestModule): Suite | File | Test;
interface TestSpecificationOptions {
testNamePattern?: RegExp;
testIds?: string[];
testLines?: number[];
testTagsFilter?: string[];
}
declare class TestSpecification {
/**
* The task id associated with the test module.
*/
readonly taskId: string;
/**
* The test project that the module belongs to.
*/
readonly project: TestProject;
/**
* The id of the module in the Vite module graph. It is usually an absolute file path.
*/
readonly moduleId: string;
/**
* The current test pool. It's possible to have multiple pools in a single test project with `typecheck.enabled`.
*/
readonly pool: Pool;
/**
* Line numbers of the test locations to run.
*/
testLines: number[] | undefined;
/**
* Regular expression pattern to filter test names.
*/
testNamePattern: RegExp | undefined;
/**
* The ids of tasks inside of this specification to run.
*/
testIds: string[] | undefined;
/**
* The tags of tests to run.
*/
testTagsFilter: string[] | undefined;
/**
* Test module associated with the specification. This will be `undefined` if tests have not been run yet.
*/
get testModule(): TestModule | undefined;
toJSON(): SerializedTestSpecification;
}
interface BrowserModuleMocker {
register: (sessionId: string, module: MockedModule) => Promise;
delete: (sessionId: string, url: string) => Promise;
clear: (sessionId: string) => Promise;
}
interface BrowserProviderOption {
name: string;
supportedBrowser?: ReadonlyArray;
options: Options;
/**
* Called once for every resolved browser project right before its shared
* Vite server is created, so the provider can start preparing the browser
* (e.g. launching it) concurrently. Optional, fire-and-forget: errors must
* surface through the normal provider flow.
*/
prewarm?: (ctx: {
config: ResolvedConfig;
vitest: Vitest;
}) => void;
providerFactory: (project: TestProject) => BrowserProvider;
serverFactory: BrowserServerFactory;
}
interface BrowserServerFactory {
(): Promise;
}
interface BrowserProvider {
name: string;
mocker?: BrowserModuleMocker;
readonly initScripts?: string[];
/**
* @experimental opt-in into file parallelisation
*/
supportsParallelism: boolean;
getCommandsContext: (sessionId: string) => Record;
openPage: (sessionId: string, url: string, options: {
parallel: boolean;
}) => Promise;
getCDPSession?: (sessionId: string) => Promise;
close: () => Awaitable;
}
type BrowserBuiltinProvider = "webdriverio" | "playwright" | "preview";
interface _BrowserNames {}
interface BrowserTraceViewOptions {
/**
* Enable Vitest trace view artifacts collection.
*
* This option controls Vitest's own trace-view pipeline, independently from provider-specific trace retention.
*
* @default false
* @experimental
*/
enabled?: boolean;
/**
* Capture canvas pixels in trace view snapshots.
*
* This uses rrweb's canvas snapshot support and can increase trace artifact size.
* In the trace viewer, this enables a weaker replay iframe sandbox because rrweb needs scripts to redraw canvas data.
*
* @default false
* @experimental
*/
recordCanvas?: boolean;
/**
* Inline loaded `![]()
` element pixels in trace view snapshots.
*
* This uses rrweb's image inlining support. It improves offline replay for still images,
* but can increase trace artifact size and does not preserve original image resource bytes.
*
* @default false
* @experimental
*/
inlineImages?: boolean;
}
type UnsupportedProperties = "browser" | "typecheck" | "alias" | "sequence" | "root" | "pool" | "runner" | "api" | "deps" | "environment" | "environmentOptions" | "server" | "benchmark" | "name";
interface BrowserInstanceOption extends Omit, Pick {
/**
* Name of the browser
*/
browser: keyof _BrowserNames extends never ? string : _BrowserNames[keyof _BrowserNames];
name?: string;
provider?: BrowserProviderOption;
}
interface BrowserConfigOptions {
/**
* if running tests in the browser should be the default
*
* @default false
*/
enabled?: boolean;
/**
* Configurations for different browser setups
*/
instances?: BrowserInstanceOption[];
/**
* Browser provider
* @example
* ```ts
* import { playwright } from '@vitest/browser-playwright'
* export default defineConfig({
* test: {
* browser: {
* provider: playwright(),
* },
* },
* })
* ```
*/
provider?: BrowserProviderOption;
/**
* enable headless mode
*
* @default process.env.CI
*/
headless?: boolean;
/**
* Show Vitest UI
*
* @default !process.env.CI
*/
ui?: boolean;
/**
* Default position for the details panel in browser mode
* 'right' shows the details panel on the right side (horizontal split)
* 'bottom' shows the details panel at the bottom (vertical split)
* @default 'right'
*/
detailsPanelPosition?: "right" | "bottom";
/**
* Default viewport size
*/
viewport?: {
/**
* Width of the viewport
* @default 414
*/
width: number;
/**
* Height of the viewport
* @default 896
*/
height: number;
};
/**
* Locator options
*/
locators?: {
/**
* Attribute used to locate elements by test id
* @default 'data-testid'
*/
testIdAttribute?: string;
/**
* Should locators match the text exactly by default
* @default true
*/
exact?: boolean;
/**
* Format used for locator "Cannot find element" error details.
*
* @default 'all'
*/
errorFormat?: "html" | "aria" | "all";
};
/**
* Generate traces that can be viewed on https://trace.playwright.dev/
*
* This option is supported only by **playwright** provider.
*/
trace?: BrowserTraceViewMode | {
mode: BrowserTraceViewMode;
/**
* The directory where all traces will be stored. By default, Vitest
* stores all traces in `__traces__` folder close to the test file.
*/
tracesDir?: string;
/**
* Whether to capture screenshots during tracing. Screenshots are used to build a timeline preview.
* @default true
*/
screenshots?: boolean;
/**
* If this option is true tracing will
* - capture DOM snapshot on every action
* - record network activity
* @default true
*/
snapshots?: boolean;
};
/**
*
* Enable Vitest trace view artifacts collection.
*
* This option controls Vitest's own trace-view pipeline, independently from provider-specific trace retention.
*
* @default false
* @experimental
*/
traceView?: boolean | BrowserTraceViewOptions;
/**
* Directory where screenshots will be saved when page.screenshot() is called
* If not set, all screenshots are saved to __screenshots__ directory in the same folder as the test file.
* If this is set, it will be resolved relative to the project root.
* @default __screenshots__
*/
screenshotDirectory?: string;
/**
* Should Vitest take screenshots if the test fails
* @default !browser.ui
*/
screenshotFailures?: boolean;
/**
* Serve sourcemaps of your dependencies (files in `node_modules`) to the
* browser during headless test runs.
*
* These sourcemaps are used by browser devtools: when disabled, pausing
* inside dependency code shows the compiled code the browser actually
* runs instead of the dependency's original sources. If you don't debug
* into your dependencies this way, disabling them makes test runs faster:
* the server doesn't generate and inline the maps, and every browser tab
* downloads several times fewer bytes.
*
* Reported test errors are not affected: stack frames pointing into a
* pre-bundled dependency are mapped using the sourcemaps stored on disk
* even when this option is disabled.
*
* Vitest never serves sourcemaps of its own pre-built modules in headless
* runs (unless `--inspect` is used) — their frames are hidden from stack
* traces anyway. Sourcemaps of your own source files are always served.
* @default true
*/
dependencySourcemaps?: boolean;
/**
* Path to the index.html file that will be used to run tests.
*/
testerHtmlPath?: string;
/**
* Scripts injected into the main window.
*/
orchestratorScripts?: BrowserScript[];
/**
* Commands that will be executed on the server
* via the browser `import("vitest/browser").commands` API.
* @see {@link https://vitest.dev/api/browser/commands}
*/
commands?: Record>;
/**
* Timeout for connecting to the browser
* @default 60000
*/
connectTimeout?: number;
expect?: {
toMatchScreenshot?: { [ComparatorName in keyof ToMatchScreenshotComparators]: {
/**
* The name of the comparator to use for visual diffing.
*
* @defaultValue `'pixelmatch'`
*/
comparatorName?: ComparatorName;
comparatorOptions?: ToMatchScreenshotComparators[ComparatorName];
} }[keyof ToMatchScreenshotComparators] & ToMatchScreenshotOptions;
};
/**
* Enables tracking uncaught errors and exceptions so they can be reported by Vitest.
*
* If you need to hide certain errors, it is recommended to use [`onUnhandledError`](https://vitest.dev/config/onunhandlederror) option instead.
*
* Disabling this will completely remove all Vitest error handlers, which can help debugging with the "Pause on exceptions" checkbox turned on.
* @default true
*/
trackUnhandledErrors?: boolean;
}
interface BrowserCommandContext {
testPath: string | undefined;
provider: BrowserProvider;
project: TestProject;
sessionId: string;
mark: (name: string, options?: MarkOptions) => Promise;
triggerCommand: (name: K, ...args: Parameters) => ReturnType;
}
interface BrowserServerStateSession {
project: TestProject;
otelCarrier?: OTELCarrier;
concurrencyId: number;
connected: () => void;
ready: () => void;
fail: (v: Error) => void;
}
interface BrowserOrchestrator {
cleanupTesters: () => Promise;
createTesters: (options: BrowserTesterOptions) => Promise;
onCancel: (reason: CancelReason) => Promise;
$close: () => void;
}
interface BrowserServerState {
orchestrators: Map;
}
interface ParentProjectBrowser {
spawn: (project: TestProject) => ProjectBrowser;
vite: ViteDevServer;
vitest: Vitest;
config: ResolvedConfig;
}
interface BrowserServerContribution {
transformIndexHtml: (ctx: IndexHtmlTransformContext) => Awaitable;
configureServer: (server: ViteDevServer) => Awaitable;
/**
* Browser-specific Vite config (`resolve.alias`, `define`, esbuild). Applied
* by the core loader plugin's `config` hook during the single project
* resolution, so other plugins observe it (e.g. alias must be baked at
* resolution time). The loader always forces `server.middlewareMode = false`
* on top. `harness` provides the package installer's `isPackageExists` (no
* `Vitest` instance is available during resolution).
*/
config: (config: UserConfig$1, harness: PluginHarness) => Awaitable;
/**
* Browser `optimizeDeps`, aggregated across every project that shares the
* single browser Vite server (instance and benchmark variants). Called by core
* after all projects are resolved and before the server is created; the result
* is merged into the resolved Vite config's `client` environment
* `optimizeDeps`. `testFiles` is the aggregated, already-globbed set of test
* files for the server (globbing lives in the core package).
*/
resolveOptimizeDeps: (projectConfigs: ResolvedConfig[], testFiles: string[], harness: PluginHarness) => Awaitable>;
/**
* Runtime plugins. Injected into the browser (`client`) environment by the
* loader's `applyToEnvironment`; their `configureServer`/`transformIndexHtml`
* are run by the loader. MUST NOT define `config`/`configResolved` hooks.
*/
plugins: Plugin[];
/**
* Constructs the `ParentBrowserProject`. Called by core at server creation,
* when the `Vitest` instance exists.
*/
createParent: (ctx: {
config: ResolvedConfig;
vitest: Vitest;
}) => ParentProjectBrowser;
/** Called by core once the server exists to wire up the browser RPC (the port may be bound later). */
setupRpc: (parent: ParentProjectBrowser) => void;
/**
* Mutable. Filled by core at server creation; the pushed `BrowserPlugin`
* closes over this same object and reads `.parent` in `configureServer`.
*/
parent?: ParentProjectBrowser;
}
interface ProjectBrowser {
vite: ViteDevServer;
state: BrowserServerState;
provider: BrowserProvider;
close: () => Promise;
initBrowserProvider: (project: TestProject) => Promise;
parseStacktrace: (stack: string) => ParsedStack[];
parseErrorStacktrace: (error: TestError, options?: StackTraceParserOptions) => ParsedStack[];
registerCommand: (name: K, cb: BrowserCommand, ReturnType>) => void;
triggerCommand: (name: K, context: BrowserCommandContext, ...args: Parameters) => ReturnType;
}
interface BrowserCommand<
Payload extends unknown[] = [],
ReturnValue = any
> {
(context: BrowserCommandContext, ...payload: Payload): Awaitable;
}
interface BrowserScript {
/**
* If "content" is provided and type is "module", this will be its identifier.
*
* If you are using TypeScript, you can add `.ts` extension here for example.
* @default `injected-${index}.js`
*/
id?: string;
/**
* JavaScript content to be injected. This string is processed by Vite plugins if type is "module".
*
* You can use `id` to give Vite a hint about the file extension.
*/
content?: string;
/**
* Path to the script. This value is resolved by Vite so it can be a node module or a file path.
*/
src?: string;
/**
* If the script should be loaded asynchronously.
*/
async?: boolean;
/**
* Script type.
* @default 'module'
*/
type?: string;
}
interface ResolvedBrowserOptions extends BrowserConfigOptions {
name: string;
enabled: boolean;
headless: boolean;
ui: boolean;
viewport: {
width: number;
height: number;
};
screenshotFailures: boolean;
locators: {
testIdAttribute: string;
exact: boolean;
errorFormat: "html" | "aria" | "all";
};
trace: {
mode: BrowserTraceViewMode;
tracesDir?: string;
screenshots?: boolean;
snapshots?: boolean;
sources?: boolean;
};
traceView: Required;
}
type ToMatchScreenshotResolvePath = (data: {
/**
* Path **without** extension, sanitized and relative to the test file.
*
* This comes from the arguments passed to `toMatchScreenshot`; if called
* without arguments this will be the auto-generated name.
*
* @example
* test('calls `onClick`', () => {
* expect(locator).toMatchScreenshot()
* // arg = "calls-onclick-1"
* })
*
* @example
* expect(locator).toMatchScreenshot('foo/bar/baz.png')
* // arg = "foo/bar/baz"
*
* @example
* expect(locator).toMatchScreenshot('../foo/bar/baz.png')
* // arg = "foo/bar/baz"
*/
arg: string;
/**
* Screenshot extension, with leading dot.
*
* This can be set through the arguments passed to `toMatchScreenshot`, but
* the value will fall back to `'.png'` if an unsupported extension is used.
*/
ext: string;
/**
* The instance's browser name.
*/
browserName: string;
/**
* The value of {@linkcode process.platform}.
*/
platform: NodeJS.Platform;
/**
* The value provided to {@linkcode ToMatchScreenshotOptions.screenshotDirectory|browser.expect.toMatchScreenshot.screenshotDirectory}, if none is provided, its default value (`__screenshots__`).
*/
screenshotDirectory: string;
/**
* Absolute path to the project's
* {@linkcode https://vitest.dev/config/root|root}.
*/
root: string;
/**
* Path to the test file, relative to the project's
* {@linkcode https://vitest.dev/config/root|root}.
*/
testFileDirectory: string;
/**
* The test's filename.
*/
testFileName: string;
/**
* The {@linkcode https://vitest.dev/api/#test|test}'s name, including
* parent {@linkcode https://vitest.dev/api/#describe|describe}, sanitized.
*/
testName: string;
/**
* The value provided to
* {@linkcode https://vitest.dev/config/attachmentsdir|attachmentsDir},
* if none is provided, its default value.
*/
attachmentsDir: string;
/**
* The {@linkcode https://vitest.dev/api/advanced/test-project|TestProject} the test belongs to.
*
* @experimental
*/
project: TestProject;
}) => string;
interface ToMatchScreenshotOptions {
/**
* The directory name used for storing reference screenshots.
*
* This value is passed as `screenshotDirectory` to {@linkcode resolveScreenshotPath|browser.expect.toMatchScreenshot.resolveScreenshotPath} and {@linkcode resolveDiffPath|browser.expect.toMatchScreenshot.resolveDiffPath}, and used in the default path resolution of `resolveScreenshotPath`.
*
* @default `__screenshots__`.
*/
screenshotDirectory?: string;
/**
* Overrides default reference screenshot path.
*
* @default path.resolve(root, testFileDirectory, screenshotDirectory, testFileName, `${arg}-${browserName}-${platform}${ext}`)
*/
resolveScreenshotPath?: ToMatchScreenshotResolvePath;
/**
* Overrides default screenshot path used for diffs.
*
* @default path.resolve(root, attachmentsDir, testFileDirectory, testFileName, `${arg}-${browserName}-${platform}${ext}`)
*/
resolveDiffPath?: ToMatchScreenshotResolvePath;
}
interface ToMatchScreenshotComparators {}
declare class BenchmarkManager {
private project;
constructor(project: TestProject);
resolve(relativePath: string): string;
readResult(relativePath: string): Promise;
writeResult(relativePath: string, data: BaselineData): Promise;
}
declare class TestProject {
/**
* The global Vitest instance.
*/
readonly vitest: Vitest;
/**
* Resolved global configuration. If there are no workspace projects, this will be the same as `config`.
*/
readonly globalConfig: ResolvedConfig;
/**
* Browser instance if the browser is enabled. This is initialized when the tests run for the first time.
*/
browser?: ProjectBrowser;
/**
* Temporary directory for the project. This is unique for each project. Vitest stores transformed content here.
*/
readonly tmpDir: string;
readonly benchmark: BenchmarkManager;
config: ResolvedConfig;
viteConfig: ResolvedConfig$1;
vite: ViteDevServer;
hash: string;
private runner;
private closingPromise;
private typecheckFilesList;
private _globalSetups?;
private _provided;
constructor(vitest: Vitest, server: ViteDevServer, viteConfig: ResolvedConfig$1, projectConfig: ResolvedConfig);
/**
* Provide a value to the test context. This value will be available to all tests with `inject`.
*/
provide: (key: T, value: ProvidedContext[T]) => void;
/**
* Get the provided context. The project context is merged with the global context.
*/
getProvidedContext(): ProvidedContext;
/**
* Creates a new test specification. Specifications describe how to run tests.
* @param moduleId The file path
*/
createSpecification(moduleId: string, locationsOrOptions?: number[] | TestSpecificationOptions | undefined, pool?: string, taskIdOverride?: string): TestSpecification;
toJSON(): SerializedTestProject;
/**
* The name of the project or an empty string if not set.
*/
get name(): string;
/**
* The color used when reporting tasks of this project.
*/
get color(): ProjectName["color"];
/**
* Serialized project configuration. This is the config that tests receive.
*/
get serializedConfig(): SerializedConfig;
/**
* Check if this is the root project. The root project is the one that has the root config.
*/
isRootProject(): boolean;
/**
* Whether the project reuses the Vite server of the config that declared it
* (see the `sharedViteServer` option). The project that owns the server
* reports `false` even when other projects reuse it.
*/
get sharedViteServer(): boolean;
onTestsRerun(cb: OnTestsRerunHandler): void;
/**
* Get all files in the project that match the globs in the config and the filters.
* @param filters String filters to match the test files.
*/
globTestFiles(filters?: string[]): Promise<{
/**
* Test files that match the filters.
*/
testFiles: string[];
/**
* Typecheck test files that match the filters. This will be empty unless `typecheck.enabled` is `true`.
*/
typecheckTestFiles: string[];
}>;
private globAllTestFiles;
isBrowserEnabled(): boolean;
private markTestFile;
/**
* Test if a file matches the test globs. This does the actual glob matching if the test is not cached, unlike `isCachedTestFile`.
*/
matchesTestGlob(moduleId: string, source?: () => string): boolean;
private filterFiles;
/**
* Closes the project and all associated resources. This can only be called once; the closing promise is cached until the server restarts.
* If the resources are needed again, create a new project.
*/
close(): Promise;
/**
* Import a file using Vite module runner.
* @param moduleId The ID of the module in Vite module graph
*/
import(moduleId: string): Promise;
private _serializeOverriddenConfig;
private clearTmpDir;
private _provideObject;
}
interface SerializedTestProject {
name: string;
serializedConfig: SerializedConfig;
context: ProvidedContext;
}
declare class TypeCheckError extends Error {
message: string;
stacks: ParsedStack[];
name: string;
constructor(message: string, stacks: ParsedStack[]);
}
interface CapturePrintErrorResult {
nearest: ParsedStack | undefined;
output: string;
}
interface ErrorOptions {
type?: string;
fullStack?: boolean;
project?: TestProject;
verbose?: boolean;
screenshotPaths?: string[];
showCodeFrame?: boolean;
}
type Listener = () => void;
declare class Logger {
outputStream: NodeJS.WriteStream | Writable;
errorStream: NodeJS.WriteStream | Writable;
private _clearScreenPending;
private _highlights;
private cleanupListeners;
console: Console;
private ctx;
constructor(outputStream?: NodeJS.WriteStream | Writable, errorStream?: NodeJS.WriteStream | Writable);
setVitest(vitest: Vitest): this;
log(...args: any[]): void;
error(...args: any[]): void;
warn(...args: any[]): void;
clearFullScreen(message?: string): void;
clearScreen(message: string, force?: boolean): void;
private _clearScreen;
printError(err: unknown, options?: ErrorOptions): void;
formatError(err: unknown, options?: ErrorOptions): CapturePrintErrorResult;
deprecate(message: string): void;
clearHighlightCache(filename?: string): void;
highlight(filename: string, source: string): string;
printNoTestTagsFound(): void;
printTags(): void;
printNoTestFound(filters?: string[]): void;
printBanner(): void;
printUnhandledErrors(errors: ReadonlyArray): void;
printSourceTypeErrors(errors: TypeCheckError[]): void;
getColumns(): number;
onTerminalCleanup(listener: Listener): void;
private addCleanupListeners;
private registerUnhandledRejection;
}
declare class VitestPackageInstaller {
isPackageExists(name: string, options?: {
paths?: string[];
}): boolean;
ensureInstalled(dependency: string, root: string, version?: string): Promise;
}
declare class PluginHarness {
logger: Logger;
packageInstaller: VitestPackageInstaller;
vitest?: Vitest;
version: string;
constructor(logger?: Logger, packageInstaller?: VitestPackageInstaller);
setVitest(vitest: Vitest | undefined): this;
getVitest(): Vitest;
}
interface Report {
/**
* The root directory for this scope.
*
* ```ts
* const report = vitest.createReport('my-json-reporter');
*
* // Is /.vitest/my-json-reporter
* const root = report.root
* ```
*/
root: string;
/**
* Clean up the report directory for this scope.
*
* By default, if `--merge-reports` is used, this method will not delete existing reports.
* To force deletion of existing reports, pass `true` as an argument.
*
* ```ts
* const report = vitest.createReport('my-json-reporter');
*
* // Removes everything inside /.vitest/my-json-reporter/
* await report.clean()
* ```
*/
clean: (force?: boolean) => Promise;
/**
* Write a file to the report directory for this scope.
* By default the file will be written with UTF-8 encoding.
* The filename is relative to the scope directory.
*
* ```ts
* const report = vitest.createReport('my-json-reporter');
*
* // Writes file to .vitest/my-json-reporter/test-report.json
* await report.writeFile('test-report.json', JSON.stringify(results))
* ```
*/
writeFile: (filename: string, content: Parameters[1], encoding?: BufferEncoding) => Promise;
/**
* Read a file from the report directory for this scope.
*
* ```ts
* const report = vitest.createReport('my-json-reporter');
*
* // Reads file from .vitest/my-json-reporter/test-report.json
* const content: string = await report.readFile('test-report.json')
* ```
*/
readFile: (filename: string, encoding?: BufferEncoding) => Promise;
/**
* Read contents of the report directory for this scope.
*
* ```ts
* const report = vitest.createReport('my-json-reporter');
*
* // Reads contents from .vitest/my-json-reporter
* const filenames: string[] = await report.readdir()
* ```
*/
readdir: () => Promise;
/**
* Delete a file from the report directory for this scope.
*
* ```ts
* const report = vitest.createReport('my-json-reporter');
*
* // Deletes file from .vitest/my-json-reporter/test-report.json
* await report.delete('test-report.json')
* ```
*/
delete: (filename: string) => Promise;
}
//#region src/tree.d.ts
/**
* A partial visitor only having the functions of interest to the caller.
*
* * `onStart(root, state)` - called before traversal begins
* * `onSummary(node, state)` - called for every summary node
* * `onDetail(node, state)` - called for every detail node
* * `onSummaryEnd(node, state)` - called after all children have been visited for
* a summary node.
* * `onEnd(root, state)` - called after traversal ends
*/
interface PartialVisitor {
onStart?(root: N, state?: any): void;
onSummary?(node: N, state?: any): void;
onDetail?(node: N, state?: any): void;
onSummaryEnd?(node: N, state?: any): void;
onEnd?(root: N, state?: any): void;
}
/**
* An object with methods that are called during the traversal of the coverage tree.
* A visitor has the following methods that are called during tree traversal.
*
* * `onStart(root, state)` - called before traversal begins
* * `onSummary(node, state)` - called for every summary node
* * `onDetail(node, state)` - called for every detail node
* * `onSummaryEnd(node, state)` - called after all children have been visited for
* a summary node.
* * `onEnd(root, state)` - called after traversal ends
*
* @param delegate - a partial visitor that only implements the methods of interest
* The visitor object supplies the missing methods as noops. For example, reports
* that only need the final coverage summary need implement `onStart` and nothing
* else. Reports that use only detailed coverage information need implement `onDetail`
* and nothing else.
* @constructor
*/
declare class Visitor {
delegate: PartialVisitor | Visitor | undefined;
onStart: (root: N, state?: any) => void;
onSummary: (node: N, state?: any) => void;
onDetail: (node: N, state?: any) => void;
onSummaryEnd: (node: N, state?: any) => void;
onEnd: (root: N, state?: any) => void;
constructor(delegate?: PartialVisitor | Visitor);
}
declare abstract class BaseNode {
abstract getParent(): BaseNode | null;
abstract getChildren(): BaseNode[];
abstract isSummary(): boolean;
isRoot(): boolean;
/**
* visit all nodes depth-first from this node down. Note that `onStart`
* and `onEnd` are never called on the visitor even if the current
* node is the root of the tree.
* @param visitor a full visitor that is called during tree traversal
* @param state optional state that is passed around
*/
visit(visitor: Visitor, state?: any): void;
}
//#region src/path.d.ts
type PathParser = (path: string) => path.ParsedPath;
declare class Path {
v: string[];
readonly length: number;
push: (...items: string[]) => number;
pop: () => string | undefined;
shift: () => string | undefined;
unshift: (...items: string[]) => number;
splice: (start: number, deleteCount?: number, ...items: string[]) => string[];
constructor(strOrArray: string | string[]);
toString(): string;
hasParent(): boolean;
parent(): Path;
elements(): string[];
name(): string;
contains(other: Path): boolean;
ancestorOf(other: Path): boolean;
descendantOf(other: Path): boolean;
commonPrefixPath(other: Path): Path;
static compare(a: Path, b: Path): number;
static tester: {
setParserAndSep(p: PathParser, sep: string): void;
reset(): void;
};
}
//#region src/coverage-summary.d.ts
/**
* Totals for a single coverage metric (statements, lines, functions, branches).
* `pct` is a percentage number (0-100), or the string `"Unknown"` for a blank
* summary that has not yet been merged with any data.
*/
interface Totals {
total: number;
covered: number;
skipped: number;
pct: number | "Unknown";
}
/**
* Raw, JSON-serializable data underlying a `CoverageSummary`.
*/
interface CoverageSummaryData {
lines: Totals;
statements: Totals;
functions: Totals;
branches: Totals;
branchesTrue?: Totals;
}
/**
* CoverageSummary provides a summary of code coverage . It exposes 4 properties,
* `lines`, `statements`, `branches`, and `functions`. Each of these properties
* is an object that has 4 keys `total`, `covered`, `skipped` and `pct`.
* `pct` is a percentage number (0-100).
*/
declare class CoverageSummary {
data: CoverageSummaryData;
readonly lines: Totals;
readonly statements: Totals;
readonly functions: Totals;
readonly branches: Totals;
readonly branchesTrue: Totals | undefined;
/**
* @constructor
* @param obj an optional data object or
* another coverage summary to initialize this object with.
*/
constructor(obj?: CoverageSummary | CoverageSummaryData);
/**
* merges a second summary coverage object into this one
* @param obj - another coverage summary object
*/
merge(obj: CoverageSummary): this;
/**
* returns a POJO that is JSON serializable. May be used to get the raw
* summary object.
*/
toJSON(): CoverageSummaryData;
/**
* return true if summary has no lines of code
*/
isEmpty(): boolean;
}
//#endregion
//#region src/file-coverage.d.ts
/** a single location in a source file: 1-based line, 0-based column */
interface Location {
line: number;
column: number;
}
/** a source range delimited by a start and end location */
interface Range {
start: Location;
end: Location;
}
/** metadata for a single function in the instrumented source */
interface FunctionMapping {
name: string;
decl: Range;
loc: Range;
line: number;
}
/** metadata for a single branch in the instrumented source */
interface BranchMapping {
loc: Range;
type: string;
locations: Range[];
line: number;
}
/**
* Raw, JSON-serializable coverage data for a single file, as produced by the
* istanbul instrumenter or coverage tooling.
*/
interface FileCoverageData {
path: string;
statementMap: Record;
fnMap: Record;
branchMap: Record;
s: Record;
f: Record;
b: Record;
/** hit counts for logical branch truthiness; only present when reportLogic is enabled */
bT?: Record;
/** marks coverage produced by the `--all` option (empty placeholder coverage) */
all?: boolean;
}
/** per-line branch coverage as returned by `FileCoverage#getBranchCoverageByLine` */
interface Coverage {
covered: number;
total: number;
coverage: number;
}
/**
* provides a read-only view of coverage for a single file.
* The deep structure of this object is documented elsewhere. It has the following
* properties:
*
* * `path` - the file path for which coverage is being tracked
* * `statementMap` - map of statement locations keyed by statement index
* * `fnMap` - map of function metadata keyed by function index
* * `branchMap` - map of branch metadata keyed by branch index
* * `s` - hit counts for statements
* * `f` - hit count for functions
* * `b` - hit count for branches
*/
declare class FileCoverage {
data: FileCoverageData;
readonly path: string;
readonly statementMap: Record;
readonly fnMap: Record;
readonly branchMap: Record;
readonly s: Record;
readonly f: Record;
readonly b: Record;
readonly bT: Record | undefined;
readonly all: boolean | undefined;
/**
* @constructor
* @param pathOrObj is a string that initializes
* and empty coverage object with the specified file path or a data object that
* has all the required properties for a file coverage object.
*/
constructor(pathOrObj?: string | FileCoverage | FileCoverageData, reportLogic?: boolean);
/**
* returns computed line coverage from statement coverage.
* This is a map of hits keyed by line number in the source.
*/
getLineCoverage(): Record;
/**
* returns an array of uncovered line numbers.
* @returns an array of line numbers for which no hits have been
* collected.
*/
getUncoveredLines(): string[];
/**
* returns a map of branch coverage by source line number.
* @returns an object keyed by line number. Each object
* has a `covered`, `total` and `coverage` (percentage) property.
*/
getBranchCoverageByLine(): Record;
/**
* return a JSON-serializable POJO for this file coverage object
*/
toJSON(): FileCoverageData;
/**
* merges a second coverage object into this one, updating hit counts
* @param other - the coverage object to be merged into this one.
* Note that the other object should have the same structure as this one (same file).
*/
merge(other: FileCoverage): void;
computeSimpleTotals(property: "getLineCoverage" | "s" | "f"): Totals;
computeBranchTotals(property: "b" | "bT"): Totals;
/**
* resets hit counts for all statements, functions and branches
* in this coverage object resulting in zero coverage.
*/
resetHits(): void;
/**
* returns a CoverageSummary for this file coverage object
* @returns {CoverageSummary}
*/
toSummary(): CoverageSummary;
}
//#endregion
//#region src/coverage-map.d.ts
/**
* Raw, JSON-serializable data underlying a `CoverageMap`: `FileCoverage`
* objects or their raw data keyed by file path. This can be the raw global
* coverage object.
*/
interface CoverageMapData {
[path: string]: FileCoverage | FileCoverageData;
}
/** CoverageMap is a map of `FileCoverage` objects keyed by file paths. */
declare class CoverageMap {
data: Record;
/**
* @constructor
* @param obj A coverage map from which to initialize this
* map's contents. This can be the raw global coverage object.
*/
constructor(obj?: CoverageMap | CoverageMapData);
/**
* merges a second coverage map into this one
* @param obj - a CoverageMap or its raw data. Coverage is merged
* correctly for the same files and additional file coverage keys are created
* as needed.
*/
merge(obj: CoverageMap | CoverageMapData): void;
/**
* filter the coveragemap based on the callback provided
* @param callback - Returns true if the path
* should be included in the coveragemap. False if it should be
* removed.
*/
filter(callback: (path: string) => boolean): void;
/**
* returns a JSON-serializable POJO for this coverage map
*/
toJSON(): CoverageMapData;
/**
* returns an array for file paths for which this map has coverage
* @returns array of files
*/
files(): string[];
/**
* returns the file coverage for the specified file.
* @param file
*/
fileCoverageFor(file: string): FileCoverage;
/**
* adds a file coverage object to this map. If the path for the object,
* already exists in the map, it is merged with the existing coverage
* otherwise a new key is added to the map.
* @param fc the file coverage to add
*/
addFileCoverage(fc: string | FileCoverage | FileCoverageData): void;
/**
* returns the coverage summary for all the file coverage objects in this map.
* @returns {CoverageSummary}
*/
getCoverageSummary(): CoverageSummary;
}
//#region src/summarizer-factory.d.ts
/** names of the summarizer strategies supported by {@link SummarizerFactory} */
type Summarizers = "flat" | "nested" | "pkg" | "defaultSummarizer";
declare class ReportNode extends BaseNode {
path: Path;
parent: ReportNode | null;
fileCoverage: FileCoverage | undefined;
children: ReportNode[];
c_files?: CoverageSummary | null;
c_full?: CoverageSummary | null;
constructor(path: Path, fileCoverage?: FileCoverage);
static createRoot(children: ReportNode[]): ReportNode;
addChild(child: ReportNode): void;
asRelative(p: string): string;
getQualifiedName(): string;
getRelativeName(): string;
getParent(): ReportNode | null;
getChildren(): ReportNode[];
isSummary(): boolean;
getFileCoverage(): FileCoverage;
getCoverageSummary(filesOnly?: boolean): CoverageSummary | null;
}
/** options accepted by {@link ReportBase} */
interface ReportBaseOptions {
/** the summarizer strategy to use when executing the report */
summarizer?: Summarizers;
}
//#region src/reports/clover/index.d.ts
/** options accepted by {@link CloverReport} */
interface CloverOptions {
/** the file to write the report to, defaults to `clover.xml` */
file?: string;
}
//#region src/reports/cobertura/index.d.ts
/** options accepted by {@link CoberturaReport} */
interface CoberturaOptions {
/** the file to write the report to, defaults to `cobertura-coverage.xml` */
file?: string;
/** timestamp to embed in the report, defaults to `Date.now()` */
timestamp?: string;
/** the project root used to relativize file paths, defaults to `process.cwd()` */
projectRoot?: string;
}
//#region src/reports/html/index.d.ts
/** maps report nodes to output paths, see the html report's `linkMapper` option */
interface LinkMapper {
getPath(node: ReportNode | string): string;
relativePath(source: ReportNode | string, target: ReportNode | string): string;
assetPath(node: ReportNode, name: string): string;
}
/** options accepted by {@link HtmlReport} */
interface HtmlOptions {
/** show extra logging while the report is generated */
verbose?: boolean;
/** maps report nodes to output paths */
linkMapper?: LinkMapper;
/** subdirectory (under the report dir) to write the report to */
subdir?: string;
/** skip nodes with no coverage */
skipEmpty?: boolean;
}
//#region src/reports/html-spa/index.d.ts
/** options accepted by {@link HtmlSpaReport} */
interface HtmlSpaOptions extends HtmlOptions {
/** the metrics to show in the report UI, defaults to lines, branches and functions */
metricsToShow?: ("lines" | "branches" | "functions" | "statements")[];
}
//#region src/reports/json-summary/index.d.ts
/** options accepted by {@link JsonSummaryReport} */
interface JsonSummaryOptions {
/** the file to write the report to, defaults to `coverage-summary.json` */
file?: string;
}
//#region src/reports/json/index.d.ts
/** options accepted by {@link JsonReport} */
interface JsonOptions$1 {
/** the file to write the report to, defaults to `coverage-final.json` */
file?: string;
}
//#region src/reports/lcovonly/index.d.ts
/** options accepted by {@link LcovOnlyReport} */
interface LcovOnlyOptions {
/** the file to write the report to, defaults to `lcov.info` */
file?: string;
/** the project root used to relativize file paths, defaults to `process.cwd()` */
projectRoot?: string;
}
//#region src/reports/lcov/index.d.ts
/** options accepted by {@link LcovReport}, passed through to the lcovonly report */
interface LcovOptions extends LcovOnlyOptions {}
//#region src/reports/teamcity/index.d.ts
/** options accepted by {@link TeamcityReport} */
interface TeamcityOptions {
/** the file to write the report to, defaults to the console */
file?: string | null;
/** the teamcity block name to wrap the output in, defaults to `Code Coverage Summary` */
blockName?: string;
}
//#region src/reports/text-lcov/index.d.ts
/** options accepted by {@link TextLcov}, `file` is always the console */
interface TextLcovOptions {
/** the project root used to relativize file paths, defaults to `process.cwd()` */
projectRoot?: string;
}
//#region src/reports/text-summary/index.d.ts
/** options accepted by {@link TextSummaryReport} */
interface TextSummaryOptions {
/** the file to write the report to, defaults to the console */
file?: string | null;
}
//#region src/reports/text/index.d.ts
/** options accepted by {@link TextReport} */
interface TextOptions extends ReportBaseOptions {
/** the file to write the report to, defaults to the console */
file?: string | null;
/** maximum column width of the table, defaults to the terminal width */
maxCols?: number;
/** skip rows with no coverage */
skipEmpty?: boolean;
/** skip rows with full coverage */
skipFull?: boolean;
}
/** options accepted by each built-in report, keyed by report name */
interface ReportOptions {
clover: CloverOptions;
cobertura: CoberturaOptions;
html: HtmlOptions;
"html-spa": HtmlSpaOptions;
json: JsonOptions$1;
"json-summary": JsonSummaryOptions;
lcov: LcovOptions;
lcovonly: LcovOnlyOptions;
none: never;
teamcity: TeamcityOptions;
text: TextOptions;
"text-lcov": TextLcovOptions;
"text-summary": TextSummaryOptions;
}
type TransformResult = string | Partial | undefined | null | void;
type CoverageResults = unknown;
interface CoverageProvider {
name: string;
/** Called when provider is being initialized before tests run */
initialize: (ctx: Vitest) => Promise | void;
/** Called when setting coverage options for Vitest context (`ctx.config.coverage`) */
resolveOptions: () => ResolvedCoverageOptions;
/** Callback to clean previous reports */
clean: (clean?: boolean) => void | Promise;
/** Called with coverage results after a single test file has been run */
onAfterSuiteRun: (meta: AfterSuiteRunMeta) => void | Promise;
/** Callback called when test run starts */
onTestRunStart?: () => void | Promise;
/** Callback called when test run fails due to test failures */
onTestFailure?: () => void | Promise;
/** Callback to generate final coverage results */
generateCoverage: (reportContext: ReportContext) => CoverageResults | Promise;
/** Callback to convert coverage results to coverage reports. Called with results returned from `generateCoverage` */
reportCoverage: (coverage: CoverageResults, reportContext: ReportContext) => void | Promise;
/** Callback for `--merge-reports` options. Called with multiple coverage results generated by `generateCoverage`. */
mergeReports?: (coverages: CoverageResults[]) => void | Promise;
/** Callback called for instrumenting files with coverage counters. */
onFileTransform?: (sourceCode: string, id: string, pluginCtx: any) => TransformResult | Promise;
/**
* Return `true` if this file is transformed by the coverage provider.
* This is used to generate the persistent file hash by `fsModuleCache`
* @experimental
*/
requiresTransform?: (id: string) => boolean;
/** Callback that's called when the coverage is enabled via a programmatic `enableCoverage` API. */
onEnabled?: () => void | Promise;
}
interface ReportContext {
/** Indicates whether all tests were run. False when only specific tests were run. */
allTestsRun?: boolean;
}
interface CoverageProviderModule extends RuntimeCoverageProviderModule {
/**
* Factory for creating a new coverage provider
*/
getProvider: () => CoverageProvider | Promise;
}
type CoverageReporter = keyof ReportOptions | (string & {});
type CoverageReporterWithOptions = ReporterName extends keyof ReportOptions ? ReportOptions[ReporterName] extends never ? [ReporterName, object] : [ReporterName, Partial] : [ReporterName, Record];
/** Fields that have default values. Internally these will always be defined. */
type FieldsWithDefaultValues = "provider" | "enabled" | "clean" | "cleanOnRerun" | "reportsDirectory" | "exclude" | "reportOnFailure" | "allowExternal" | "processingConcurrency" | "reporter" | "excludeAfterRemap" | "ignoreClassMethods" | "skipFull" | "watermarks" | "autoAttachSubprocess";
type ResolvedCoverageOptions = CoverageOptions & Required> & {
reporter: CoverageReporterWithOptions[];
htmlDir?: string;
};
interface CoverageOptions {
/**
* Coverage provider to use.
*
* @default 'v8'
*/
provider?: "v8" | "istanbul" | "custom";
/**
* Enables coverage collection. Can be overridden using `--coverage` CLI option.
*
* @default false
*/
enabled?: boolean;
/**
* List of files included in coverage as glob patterns.
* By default only files covered by tests are included.
*
* See [Including and excluding files from coverage report](https://vitest.dev/guide/coverage.html#including-and-excluding-files-from-coverage-report) for examples.
*/
include?: string[];
/**
* List of files excluded from coverage as glob patterns.
* Files are first checked against `coverage.include`.
*
* See [Including and excluding files from coverage report](https://vitest.dev/guide/coverage.html#including-and-excluding-files-from-coverage-report) for examples.
*/
exclude?: string[];
/**
* Clean coverage results before running tests
*
* @default true
*/
clean?: boolean;
/**
* Clean coverage report on watch rerun
*
* @default true
*/
cleanOnRerun?: boolean;
/**
* Directory to write coverage report to
*
* @default './coverage'
*/
reportsDirectory?: string;
/**
* Coverage reporters to use.
* See [istanbul documentation](https://istanbul.js.org/docs/advanced/alternative-reporters/) for detailed list of all reporters.
*
* @default ['text', 'html', 'clover', 'json']
*/
reporter?: Arrayable | (CoverageReporter | [CoverageReporter] | CoverageReporterWithOptions)[];
/**
* Do not show files with 100% statement, branch, and function coverage
*
* @default false
*/
skipFull?: boolean;
/**
* Configurations for thresholds
*
* @example
*
* ```ts
* {
* // Thresholds for all files
* functions: 95,
* branches: 70,
* perFile: true,
* autoUpdate: true,
*
* // Thresholds for utilities
* 'src/utils/**.ts': {
* lines: 100,
* statements: 95,
* }
* }
* ```
*/
thresholds?: Thresholds | ({
[glob: string]: Pick;
} & Thresholds);
/**
* Watermarks for statements, lines, branches and functions.
*
* Default value is `[50,80]` for each property.
*/
watermarks?: {
statements?: [number, number];
functions?: [number, number];
branches?: [number, number];
lines?: [number, number];
};
/**
* Generate coverage report even when tests fail.
*
* @default false
*/
reportOnFailure?: boolean;
/**
* Collect coverage of files outside the project `root`.
*
* @default false
*/
allowExternal?: boolean;
/**
* Apply exclusions again after coverage has been remapped to original sources.
* This is useful when your source files are transpiled and may contain source maps
* of non-source files.
*
* Use this option when you are seeing files that show up in report even if they
* match your `coverage.exclude` patterns.
*
* @default false
*/
excludeAfterRemap?: boolean;
/**
* Concurrency limit used when processing the coverage results.
* Defaults to `Math.min(20, os.availableParallelism?.() ?? os.cpus().length)`
*/
processingConcurrency?: number;
/**
* Track coverage of the `node:child_process` and `node:worker_threads` spawned during test run.
* Supported only by `v8` provider.
*
* @default false
*/
autoAttachSubprocess?: boolean;
/**
* Set to array of class method names to ignore for coverage
*
* @default []
*/
ignoreClassMethods?: string[];
/**
* Custom instrumenter factory to use instead of the default `@vitest/istanbul-lib-instrument`.
*
* The factory receives the same runtime coverage options Vitest passes to its
* built-in Istanbul instrumenter and must return an object implementing the
* `CoverageInstrumenter` interface.
*
* This allows using faster instrumenters (e.g., oxc-coverage-instrument, SWC) while
* keeping the Istanbul coverage pipeline for collection, merging, and reporting.
*
* @example
* ```ts
* import { defineConfig } from 'vitest/config'
* import { createOxcInstrumenter } from 'oxc-coverage-instrument/vitest'
*
* export default defineConfig({
* test: {
* coverage: {
* provider: 'istanbul',
* instrumenter: options => createOxcInstrumenter(options),
* }
* }
* })
*
* @experimental
*/
instrumenter?: (options: InstrumenterOptions) => CoverageInstrumenter;
/**
* Directory of HTML coverage output to be served in UI mode and HTML reporter.
* This is automatically configured for builtin reporter with html output (`html`, `html-spa`, and `lcov` reporters).
* Use this option to override with custom coverage reporting location.
*/
htmlDir?: string;
/**
* Collect coverage only for files changed since a specified commit or branch.
* Inherits the default value from `test.changed`.
*/
changed?: boolean | string;
/**
* Name of the module or path to a file to load the custom provider from
*/
customProviderModule?: string;
}
interface Thresholds {
/** Set global thresholds to `100` */
100?: boolean;
/**
* Check thresholds per file. When set to an object, the top-level thresholds
* still apply to the aggregate and every file must additionally meet these
* per-file minimums.
*
* Can also be set per glob pattern via `thresholds[''].perFile`. Glob
* patterns do not inherit this top-level `perFile`; set it on each glob
* explicitly.
*
* @default false
*/
perFile?: boolean | Pick;
/**
* Update threshold values automatically when current coverage is higher than earlier thresholds
* Also can accept a function to format the new threshold values
*
* @default false
*/
autoUpdate?: boolean | ((newThreshold: number, previousThreshold: number) => number);
/** Thresholds for statements */
statements?: number;
/** Thresholds for functions */
functions?: number;
/** Thresholds for branches */
branches?: number;
/** Thresholds for lines */
lines?: number;
}
/**
* Options passed to the custom instrumenter factory.
*/
interface InstrumenterOptions {
/** Global variable name that Vitest uses to store coverage data at runtime. */
coverageVariable: string;
/** Global scope where the coverage variable is attached at runtime. */
coverageGlobalScope: string;
/** Whether the coverage global scope should be resolved through an evaluated function. */
coverageGlobalScopeFunc: boolean;
/** Class method names to exclude from function coverage. */
ignoreClassMethods: string[];
}
/**
* Interface for custom coverage instrumenters.
*
* Matches the subset of istanbul-lib-instrument's `Instrumenter` that Vitest
* actually uses. Implement this to plug in a faster instrumenter while keeping
* the Istanbul coverage pipeline for collection, merging, and reporting.
*/
interface CoverageInstrumenter {
/** Instrument source code synchronously. Returns the instrumented code string. */
instrumentSync: (code: string, filename: string, inputSourceMap?: any) => string;
/** Get the source map of the last instrumented file. */
lastSourceMap: () => any;
/** Get the Istanbul-compatible file coverage object of the last instrumented file. */
lastFileCoverage: () => any;
}
/** @deprecated Use `CoverageOptions` instead */
interface CoverageV8Options extends CoverageOptions {}
/** @deprecated Use `CoverageOptions` instead */
interface CoverageIstanbulOptions extends CoverageOptions {}
/** @deprecated Use `CoverageOptions` instead */
interface BaseCoverageOptions extends CoverageOptions {}
/** @deprecated Use `CoverageOptions` instead */
interface CustomProviderOptions extends CoverageOptions {}
interface TestRunResult {
testModules: TestModule[];
unhandledErrors: unknown[];
}
interface VCSProviderOptions {
root: string;
changedSince?: string | boolean;
}
interface VCSProvider {
findChangedFiles(options: VCSProviderOptions): Promise;
}
declare class SnapshotManager {
options: Omit;
summary: SnapshotSummary;
extension: string;
constructor(options: Omit);
clear(): void;
add(result: SnapshotResult): void;
resolvePath(testPath: string, context?: T): string;
resolveRawPath(testPath: string, rawPath: string): string;
}
interface SuiteResultCache {
failed: boolean;
duration: number;
}
declare class ResultsCache {
private logger;
private cache;
private workspacesKeyMap;
private cachePath;
private version;
private root;
constructor(logger: Logger);
getCachePath(): string | null;
setConfig(root: string, config: ResolvedConfig["cache"]): void;
getResults(key: string): SuiteResultCache | undefined;
clearCache(): Promise;
readFromCache(): Promise;
updateResults(files: File[]): void;
removeFromCache(filepath: string): void;
writeToCache(): Promise;
}
type FileStatsCache = Pick;
declare class FilesStatsCache {
cache: Map;
getStats(key: string): FileStatsCache | undefined;
populateStats(root: string, specs: TestSpecification[]): Promise;
updateStats(fsPath: string, key: string): Promise;
removeStats(fsPath: string): void;
}
declare class VitestCache {
results: ResultsCache;
stats: FilesStatsCache;
constructor(logger: Logger);
getFileTestResults(key: string): SuiteResultCache | undefined;
getFileStats(key: string): {
size: number;
} | undefined;
static resolveCacheDir(root: string, dir?: string, projectName?: string): string;
}
type TestRunEndReason = "passed" | "interrupted" | "failed";
interface Reporter {
onInit?: (vitest: Vitest) => void;
/**
* Called when the project initiated the browser instance.
* project.browser will always be defined.
*/
onBrowserInit?: (project: TestProject) => Awaitable;
onTestRemoved?: (trigger?: string) => Awaitable;
onWatcherStart?: (files?: File[], errors?: unknown[]) => Awaitable;
onWatcherRerun?: (files: string[], trigger?: string) => Awaitable;
onServerRestart?: (reason?: string) => Awaitable;
onUserConsoleLog?: (log: UserConsoleLog) => Awaitable;
onProcessTimeout?: () => Awaitable;
/**
* Called when the new test run starts.
*/
onTestRunStart?: (specifications: ReadonlyArray) => Awaitable;
/**
* Called when the test run is finished.
*/
onTestRunEnd?: (testModules: ReadonlyArray, unhandledErrors: ReadonlyArray, reason: TestRunEndReason) => Awaitable;
/**
* Called when the module is enqueued for testing. The file itself is not loaded yet.
*/
onTestModuleQueued?: (testModule: TestModule) => Awaitable;
/**
* Called when the test file is loaded and the module is ready to run tests.
*/
onTestModuleCollected?: (testModule: TestModule) => Awaitable;
/**
* Called when starting to run tests of the test file
*/
onTestModuleStart?: (testModule: TestModule) => Awaitable;
/**
* Called when all tests of the test file have finished running.
*/
onTestModuleEnd?: (testModule: TestModule) => Awaitable;
/**
* Called when test case is ready to run.
* Called before the `beforeEach` hooks for the test are run.
*/
onTestCaseReady?: (testCase: TestCase) => Awaitable;
/**
* Called after the test and its hooks are finished running.
* The `result()` cannot be `pending`.
*/
onTestCaseResult?: (testCase: TestCase) => Awaitable;
/**
* Called when annotation is added via the `task.annotate` API.
*/
onTestCaseAnnotate?: (testCase: TestCase, annotation: TestAnnotation) => Awaitable;
/**
* Called when artifacts are recorded on tests via the `recordArtifact` utility.
*/
onTestCaseArtifactRecord?: (testCase: TestCase, artifact: TestArtifact) => Awaitable;
/**
* Called when test suite is ready to run.
* Called before the `beforeAll` hooks for the test are run.
*/
onTestSuiteReady?: (testSuite: TestSuite) => Awaitable;
/**
* Called after the test suite and its hooks are finished running.
* The `state` cannot be `pending`.
*/
onTestSuiteResult?: (testSuite: TestSuite) => Awaitable;
/**
* Called before the hook starts to run.
*/
onHookStart?: (hook: ReportedHookContext) => Awaitable;
/**
* Called after the hook finished running.
*/
onHookEnd?: (hook: ReportedHookContext) => Awaitable;
onCoverage?: (coverage: unknown) => Awaitable;
/**
* @experimental
* Called after the benchmark is finished.
*/
onTestCaseBenchmark?: (testCase: TestCase, benchmark: TestBenchmark) => Awaitable;
}
interface BlobOptions {
outputFile?: string;
label?: string;
}
declare class BlobReporter implements Reporter {
start: number;
ctx: Vitest;
options: BlobOptions;
coverage: unknown | undefined;
constructor(options: BlobOptions);
onInit(ctx: Vitest): void;
onCoverage(coverage: unknown): void;
onTestRunEnd(testModules: ReadonlyArray, unhandledErrors: ReadonlyArray): Promise;
}
interface MergedBlobs {
files: File[];
errors: unknown[];
coverages: unknown[];
executionTimes: number[];
}
declare class StateManager {
filesMap: Map;
pathsSet: Set;
idMap: Map;
taskFileMap: WeakMap;
errorsSet: Set;
leakSet: Set;
reportedTasksMap: WeakMap;
blobs?: MergedBlobs;
/**
* Total time spent starting test workers (spawning the process/thread, loading
* the worker bundle and setting up the test environment). Used to surface the
* cost of `isolate: true`, which spawns a fresh worker per test file.
*/
startupTime: number;
/** Number of test workers that were started during the run. */
workersSpawned: number;
metadata: Record;
duration: Record;
tmps: Record;
dumpDir?: string;
outline?: {
externalized: number;
inlined: number;
};
}>;
onUnhandledError?: OnUnhandledErrorCallback;
constructor(options: {
onUnhandledError?: OnUnhandledErrorCallback;
});
catchError(error: unknown, type: string): void;
catchLeaks(leaks: AsyncLeak[]): void;
clearErrors(): void;
getUnhandledErrors(): unknown[];
getPaths(): string[];
/**
* Return files that were running or collected.
*/
getFiles(keys?: string[]): File[];
getTestModules(keys?: string[]): TestModule[];
getFilepaths(): string[];
getFailedFilepaths(): string[];
collectPaths(paths?: string[]): void;
collectFiles(project: TestProject, files?: File[]): void;
clearFiles(project: TestProject, paths?: string[]): void;
updateId(task: Task, project: TestProject): void;
getReportedEntity(task: Task): TestModule | TestCase | TestSuite | undefined;
getReportedEntityById(taskId: string): TestModule | TestCase | TestSuite | undefined;
updateTasks(packs: TaskResultPack[]): void;
updateUserLog(log: UserConsoleLog): void;
getCountOfFailedTests(): number;
cancelFiles(files: FileSpecification[], project: TestProject): void;
}
declare class VitestWatcher {
private vitest;
/**
* Modules that will be invalidated on the next run.
*/
readonly invalidates: Set;
/**
* Test files that have changed and need to be rerun.
*/
readonly changedTests: Set;
private readonly _onRerun;
constructor(vitest: Vitest);
close(): void;
unregisterWatcher: () => void;
registerWatcher(): this;
private scheduleRerun;
private getTestFilesFromWatcherTrigger;
onFileChange: (id: string) => void;
onFileDelete: (id: string) => void;
onFileCreate: (id: string) => void;
private handleSetupFile;
/**
* @returns A value indicating whether rerun is needed (changedTests was mutated)
*/
private handleFileChanged;
}
interface WatcherTriggerPattern {
pattern: RegExp;
testsToRun: (file: string, match: RegExpMatchArray) => string[] | string | null | undefined | void;
}
interface VitestOptions {
packageInstaller?: VitestPackageInstaller;
stdin?: NodeJS.ReadStream;
stdout?: NodeJS.WriteStream | Writable;
stderr?: NodeJS.WriteStream | Writable;
}
declare class Vitest {
/**
* Current Vitest version.
* @example '2.0.0'
*/
readonly version: string;
static readonly version: string;
/**
* The logger instance used to log messages. It's recommended to use this logger instead of `console`.
* It's possible to override stdout and stderr streams when initiating Vitest.
* @example
* new Vitest({
* stdout: new Writable(),
* })
*/
readonly logger: Logger;
/**
* The package installer instance used to install Vitest packages.
* @example
* await vitest.packageInstaller.ensureInstalled('@vitest/browser', process.cwd())
*/
readonly packageInstaller: VitestPackageInstaller;
/**
* A path to the built Vitest directory. This is usually a folder in `node_modules`.
*/
readonly distPath: string;
/**
* A list of projects that are currently running.
* If projects were filtered with `--project` flag, they won't appear here.
*/
projects: TestProject[];
/**
* A watcher handler. This is not the file system watcher. The handler only
* exposes methods to handle changed files.
*
* If you have your own watcher, you can use these methods to replicate
* Vitest behaviour.
*/
readonly watcher: VitestWatcher;
/**
* The version control system provider used to detect changed files.
* This is used with the `--changed` flag to determine which test files to run.
* By default, Vitest uses Git. You can provide a custom implementation via
* `experimental.vcsProvider` in your config.
*/
vcs: VCSProvider;
/**
* The global config.
*/
config: ResolvedConfig;
/**
* Resolved global vite config.
*/
viteConfig: ResolvedConfig$1;
/**
* Global Vite's dev server instance.
*/
vite: ViteDevServer;
/**
* The global test state manager.
* @experimental The State API is experimental and not subject to semver.
*/
state: StateManager;
/**
* The global snapshot manager. You can access the current state on `snapshot.summary`.
*/
snapshot: SnapshotManager;
/**
* Test results and test file stats cache. Primarily used by the sequencer to sort tests.
*/
cache: VitestCache;
private _warnedExperimentalCacheKeyGenerator;
private isFirstRun;
private restartsCount;
private readonly specifications;
private pool;
private _coverageProvider?;
/**
* @deprecated Do not rely on this property, it's always `test`. Scheduled to be removed in the next major.
*/
readonly mode = "test";
constructor(harness: PluginHarness, viteConfig: ResolvedConfig$1);
private _onRestartListeners;
private _onClose;
private _onSetServer;
private _onCancelListeners;
private _onUserTestsRerun;
private _onFilterWatchedSpecification;
private _restartPromise?;
private _restartQueued;
private _restart;
private _restartNow;
listTags(): Promise;
enableCoverage(): Promise;
disableCoverage(): void;
private clearAllCachePaths;
private _coverageOverrideCache;
/**
* 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;
/**
* Provide a value to the test context. This value will be available to all tests with `inject`.
*/
provide: (key: T, value: ProvidedContext[T]) => void;
/**
* Get global provided context.
*/
getProvidedContext(): ProvidedContext;
/**
* Return project that has the root (or "global") config.
*/
getRootProject(): TestProject;
get serializedRootConfig(): SerializedRootConfig;
getProjectByName(name: string): TestProject;
/**
* Import a file using Vite module runner. The file will be transformed by Vite and executed in a separate context.
* @param moduleId The ID of the module in Vite module graph
*/
import(moduleId: string): Promise;
/**
* Creates a coverage provider if `coverage` is enabled in the config.
*/
createCoverageProvider(): Promise;
/**
* Glob test files in every project and create a TestSpecification for each file and pool.
* @param filters String filters to match the test files.
*/
globTestSpecifications(filters?: string[]): Promise;
private initCoverageProvider;
/**
* @deprecated Use `clearCache` instead.
*/
experimental_clearCache(): Promise;
/**
* Deletes all Vitest caches, including the `fsModuleCache`.
*/
clearCache(): Promise;
/**
* Merge reports from multiple runs located in the specified directory (value from `--merge-reports` if not specified).
*/
mergeReports(directory?: string): Promise;
/**
* Returns the seed, if tests are running in a random order.
*/
getSeed(): number | null;
collect(filters?: string[], options?: {
staticParse?: boolean;
staticParseConcurrency?: number;
}): Promise;
/**
* Returns the list of test files that match the config and filters.
* @param filters String filters to match the test files
*/
getRelevantTestSpecifications(filters?: string[]): Promise;
/**
* Initialize reporters, the coverage provider, and run tests.
* This method can throw an error:
* - `FilesNotFoundError` if no tests are found
* - `GitNotFoundError` if `--related` flag is used, but git repository is not initialized
* - `Error` from the user reporters
* @param filters String filters to match the test files
*/
start(filters?: string[]): Promise;
/**
* @deprecated use `standalone()` instead
*/
init(): Promise;
/**
* Initialize reporters and the coverage provider. This method doesn't run any tests.
* If the `--watch` flag is provided, Vitest will still run changed tests even if this method was not called.
*/
standalone(): Promise;
/**
* If there is a test run happening, returns a promise that will
* resolve when the test run is finished.
*/
waitForTestRunEnd(): Promise;
/**
* Get test specifications associated with the given module. If module is not a test file, an empty array is returned.
*
* **Note:** this method relies on a cache generated by `globTestSpecifications`. If the file was not processed yet, use `project.matchesGlobPattern` instead.
* @param moduleId The module ID to get test specifications for.
*/
getModuleSpecifications(moduleId: string): TestSpecification[];
/**
* Vitest automatically caches test specifications for each file. This method clears the cache for the given file or the whole cache altogether.
*/
clearSpecificationsCache(moduleId?: string): void;
/**
* Run tests for the given test specifications. This does not trigger `onWatcher*` events.
* @param specifications A list of specifications to run.
* @param allTestsRun Indicates whether all tests were run. This only matters for coverage.
*/
runTestSpecifications(specifications: TestSpecification[], allTestsRun?: boolean): Promise;
/**
* Runs tests for the given file paths. This does not trigger `onWatcher*` events.
* @param filepaths A list of file paths to run tests for.
* @param allTestsRun Indicates whether all tests were run. This only matters for coverage.
*/
runTestFiles(filepaths: string[], allTestsRun?: boolean): Promise;
/**
* Rerun files and trigger `onWatcherRerun`, `onWatcherStart` and `onTestsRerun` events.
* @param specifications A list of specifications to run.
* @param allTestsRun Indicates whether all tests were run. This only matters for coverage.
*/
rerunTestSpecifications(specifications: TestSpecification[], allTestsRun?: boolean): Promise;
private runFiles;
/**
* Returns module's diagnostic. If `testModule` is not provided, `selfTime` and `totalTime` will be aggregated across all tests.
*
* If the module was not transformed or executed, the diagnostic will be empty.
* @experimental
* @see {@link https://vitest.dev/api/advanced/vitest#getsourcemodulediagnostic}
*/
experimental_getSourceModuleDiagnostic(moduleId: string, testModule?: TestModule): Promise;
/**
* @deprecated Use `parseSpecifications` instead
*/
experimental_parseSpecifications(specifications: TestSpecification[], options?: {
/** @default os.availableParallelism() */
concurrency?: number;
}): Promise;
parseSpecifications(specifications: TestSpecification[], options?: {
/** @default os.availableParallelism() */
concurrency?: number;
}): Promise;
experimental_parseSpecification(specification: TestSpecification): Promise;
/**
* Collect tests in specified modules. Vitest will run the files to collect tests.
* @param specifications A list of specifications to run.
*/
collectTests(specifications: TestSpecification[]): Promise;
/**
* Gracefully cancel the current test run. Vitest will wait until all running tests are finished before cancelling.
*/
cancelCurrentRun(reason: CancelReason): Promise;
private initializeGlobalSetup;
/**
* Update snapshots in specified files. If no files are provided, it will update files with failed tests and obsolete snapshots.
* @param files The list of files on the file system
*/
updateSnapshot(files?: string[]): Promise;
/**
* Enable the mode that allows updating snapshots when running tests.
* This method doesn't run any tests.
*
* Every test that runs after this method is called will update snapshots.
* To disable the mode, call `resetSnapshotUpdate`.
*/
enableSnapshotUpdate(): void;
/**
* Disable the mode that allows updating snapshots when running tests.
*/
resetSnapshotUpdate(): void;
/**
* Set the global test name pattern to a regexp.
* This method doesn't run any tests.
*/
setGlobalTestNamePattern(pattern: string | RegExp): void;
/**
* Returns the regexp used for the global test name pattern.
*/
getGlobalTestNamePattern(): RegExp | undefined;
/**
* Resets the global test name pattern. This method doesn't run any tests.
*/
resetGlobalTestNamePattern(): void;
private _rerunTimer;
private scheduleRerun;
/**
* Invalidate a file in all projects.
*/
invalidateFile(filepath: string): void;
private reportCoverage;
/**
* Closes all projects and their associated resources.
* This can only be called once; the closing promise is cached until the server restarts.
*/
close(): Promise;
/**
* Removes the root temp directory with the tmp module copies,
* mirroring `TestProject.clearTmpDir()`. The reference is cleared before
* the removal so a repeated close is a no-op.
*/
private _clearTmpDir;
/**
* Closes all projects and exit the process
* @param force If true, the process will exit immediately after closing the projects.
*/
exit(force?: boolean): Promise;
/**
* Should the server be kept running after the tests are done.
*/
shouldKeepServer(): boolean;
/**
* Register a handler that will be called when the server is restarted due to a config change.
*/
onServerRestart(fn: OnServerRestartHandler): void;
/**
* Register a handler that will be called when the test run is cancelled with `vitest.cancelCurrentRun`.
*/
onCancel(fn: (reason: CancelReason) => Awaitable): () => void;
/**
* Register a handler that will be called when the server is closed.
*/
onClose(fn: () => Awaitable): void;
/**
* Register a handler that will be called when the tests are rerunning.
*/
onTestsRerun(fn: OnTestsRerunHandler): void;
/**
* Register a handler that will be called when a file is changed.
* This callback should return `true` of `false` indicating whether the test file needs to be rerun.
* @example
* const testsToRun = [resolve('./test.spec.ts')]
* vitest.onFilterWatchedSpecification(specification => testsToRun.includes(specification.moduleId))
*/
onFilterWatchedSpecification(fn: (specification: TestSpecification) => boolean): void;
/**
* Check if the project with a given name should be included.
*/
matchesProjectFilter(name: string): boolean;
/**
* Create a report that's scoped to a specific reporter directory.
*/
createReport(scope: string): Report;
}
type OnServerRestartHandler = (reason?: string) => Promise | void;
type OnTestsRerunHandler = (testFiles: TestSpecification[]) => Promise | void;
interface CliOptions extends UserConfig {
/**
* Override the watch mode
*/
run?: boolean;
/**
* Removes colors from the console output
*/
color?: boolean;
/**
* Output collected tests as JSON or to a file
*/
json?: string | boolean;
/**
* Output collected test files only
*/
filesOnly?: boolean;
/**
* Parse files statically instead of running them to collect tests
* @default true
*/
staticParse?: boolean;
/**
* How many tests to process at the same time
* @default os.availableParallelism()
*/
staticParseConcurrency?: number;
/**
* Override vite config's configLoader from CLI.
* Use `bundle` to bundle the config with esbuild or `runner` (experimental) to process it on the fly (default: `bundle`).
* This is only available with **vite version 6.1.0** and above.
* @experimental
*/
configLoader?: InlineConfig$1 extends {
configLoader?: infer T;
} ? T : never;
}
/**
* Start Vitest programmatically
*
* Returns a Vitest instance if initialized successfully.
*/
declare function startVitest(cliFilters?: string[], options?: CliOptions, viteOverrides?: UserConfig$1, vitestOptions?: VitestOptions): Promise;
/**
* @deprecated The `mode` argument is no longer used. Use `startVitest(cliFilters?, options?, viteOverrides?, vitestOptions?)` instead.
*/
declare function startVitest(mode: VitestRunMode, cliFilters?: string[], options?: CliOptions, viteOverrides?: UserConfig$1, vitestOptions?: VitestOptions): Promise;
interface PoolRunnerInitializer {
readonly name: string;
createPoolWorker: (options: PoolOptions) => PoolWorker;
}
interface PoolOptions {
distPath: string;
project: TestProject;
method: "run" | "collect";
cacheFs?: boolean;
environment: ContextTestEnvironment;
execArgv: string[];
env: Partial;
}
interface PoolWorker {
readonly name: string;
readonly reportMemory?: boolean;
readonly cacheFs?: boolean;
on: (event: string, callback: (...args: any[]) => void) => void;
off: (event: string, callback: (...args: any[]) => void) => void;
send: (message: WorkerRequest) => void;
deserialize: (data: unknown) => unknown;
start: () => Promise;
stop: () => Promise;
/**
* This is called on workers that already satisfy certain constraints:
* - The task has the same worker name
* - The task has the same project
*/
canReuse?: (task: PoolTask) => boolean;
}
interface PoolTask {
worker: "forks" | "threads" | "vmForks" | "vmThreads" | (string & {});
project: TestProject;
isolate: boolean;
/**
* Custom `process.env`. All tasks in the same project will reference the same object,
* so modifying it once will modify it for every task.
*/
env: Partial;
/**
* Custom `execArgv`. All tasks in the same project will reference the same array,
* so modifying it once will modify it for every task.
*/
execArgv: string[];
context: WorkerExecuteContext;
memoryLimit: number | null;
}
type WorkerRequest = {
__vitest_worker_request__: true;
} & ({
type: "start";
poolId: number;
workerId: WorkerExecuteContext["workerId"];
options: {
reportMemory: boolean;
};
context: {
environment: WorkerTestEnvironment;
config: SerializedConfig;
pool: string;
};
traces: {
enabled: boolean;
sdkPath?: string;
otelCarrier?: OTELCarrier;
};
} | {
type: "stop";
otelCarrier?: OTELCarrier;
} | {
type: "run";
context: WorkerExecuteContext;
otelCarrier?: OTELCarrier;
} | {
type: "collect";
context: WorkerExecuteContext;
otelCarrier?: OTELCarrier;
} | {
type: "cancel";
});
type WorkerResponse = {
__vitest_worker_response__: true;
} & ({
type: "started";
error?: unknown;
} | {
type: "stopped";
error?: unknown;
} | {
type: "testfileFinished";
usedMemory?: number;
error?: unknown;
});
interface BaseOptions {
isTTY?: boolean;
silent?: boolean | "passed-only";
}
declare abstract class BaseReporter implements Reporter {
start: number;
end: number;
watchFilters?: string[];
failedUnwatchedFiles: TestModule[];
isTTY: boolean;
ctx: Vitest;
renderSucceed: boolean;
protected verbose: boolean;
protected silent?: boolean | "passed-only";
private _filesInWatchMode;
private _timeStart;
private _perProjectBenchmarks;
private _printedSuites;
constructor(options?: BaseOptions);
onInit(ctx: Vitest): void;
log(...messages: any): void;
error(...messages: any): void;
relative(path: string): string;
onTestRunStart(_specifications: ReadonlyArray): void;
onTestRunEnd(testModules: ReadonlyArray, unhandledErrors: ReadonlyArray, _reason: TestRunEndReason): void;
onTestCaseResult(testCase: TestCase): void;
onTestCaseBenchmark(testCase: TestCase, benchmark: TestBenchmark): void;
onTestSuiteResult(testSuite: TestSuite): void;
onTestModuleEnd(testModule: TestModule): void;
protected logFailedTask(task: Task): void;
protected printTestModule(testModule: TestModule): void;
protected printTestCase(moduleState: TestModuleState, test: TestCase): void;
private getModuleLog;
protected printTestSuite(testSuite: TestSuite): void;
private printSuiteEntry;
private printAncestorSuites;
protected getTestName(test: Task, _separator?: string): string;
protected getFullName(test: Task, separator?: string): string;
protected getTestIndentation(test: Task): string;
protected printAnnotations(test: TestCase, console: "log" | "error", padding?: number): void;
protected getEntityPrefix(entity: TestCase | TestModule | TestSuite): string;
protected getTestCaseSuffix(testCase: TestCase): string;
protected getStateSymbol(test: TestCase | TestModule | TestSuite): string;
private getDurationPrefix;
onWatcherStart(files?: File[], errors?: unknown[]): void;
onWatcherRerun(files: string[], trigger?: string): void;
onUserConsoleLog(log: UserConsoleLog, taskState?: TestResult["state"]): void;
onTestRemoved(trigger?: string): void;
shouldLog(log: UserConsoleLog, taskState?: TestResult["state"]): boolean;
onServerRestart(reason?: string): void;
reportSummary(files: File[], errors: unknown[]): void;
reportTestSummary(files: File[], errors: unknown[], leakCount: number): void;
private getEffectiveMaxWorkers;
/**
* Surfaces the cost of re-creating a DOM environment for every test file:
* with an isolating pool, `jsdom`/`happy-dom` are imported and set up once
* per file. When that repeated setup dominates the run, hint that a `vm`
* pool sets the environment up once per worker while keeping per-file
* isolation, and that `isolate: false` shares it across files.
*/
private reportEnvironmentDiagnostic;
/**
* Surfaces repeated evaluation of the same module graph: with `isolate: true`
* every test file re-imports its whole graph, so suites where files share
* most of their modules (typically through barrel files) pay the graph cost
* once per file. The duplication is measured from server-side fetch counts,
* so suites with disjoint per-file graphs stay quiet.
*/
private reportImportDiagnostic;
/**
* Surfaces transform-dominated runs: without the fs module cache every
* `vitest run` transforms the whole module graph from scratch. Enabling
* `fsModuleCache` persists the results so the next run skips them.
*/
private reportTransformDiagnostic;
/**
* Surfaces the cost of `isolate: true`: with isolation enabled Vitest spawns a
* fresh worker (and re-creates the test environment) for every test file. When
* that repeated startup cost is significant, hint that `isolate: false` would
* reuse workers across files.
*/
private reportIsolateDiagnostic;
private reportImportDurations;
private importDurationTime;
private ellipsisPath;
private printErrorsSummary;
private printLeaksSummary;
protected printPerProjectBenchmarks(): void;
protected printBenchmarkTable(benchmarks: readonly TestBenchmark[], basePadding: string, columnName?: string): void;
private printTaskErrors;
}
interface DefaultReporterOptions extends BaseOptions {
summary?: boolean;
}
declare class DefaultReporter extends BaseReporter {
private options;
private summary?;
constructor(options?: DefaultReporterOptions);
onTestRunStart(specifications: ReadonlyArray): void;
onTestRunEnd(testModules: ReadonlyArray, unhandledErrors: ReadonlyArray, reason: TestRunEndReason): void;
onTestModuleQueued(file: TestModule): void;
onTestModuleCollected(module: TestModule): void;
onTestModuleEnd(module: TestModule): void;
onTestCaseReady(test: TestCase): void;
onTestCaseResult(test: TestCase): void;
onHookStart(hook: ReportedHookContext): void;
onHookEnd(hook: ReportedHookContext): void;
onInit(ctx: Vitest): void;
}
interface GithubActionsReporterOptions {
onWritePath?: (path: string) => string;
/**
* @default true
*/
displayAnnotations?: boolean;
/**
* Configuration for the GitHub Actions Job Summary.
*
* When enabled, a markdown summary of test results is written to the path specified by `outputPath`.
*/
jobSummary?: Partial;
}
interface JobSummaryOptions {
/**
* Title of the summary.
*
* @default 'Vitest Test Report'
*/
title: string;
/**
* Whether to generate the summary.
*
* @default true
*/
enabled: boolean;
/**
* File path to write the summary to.
*
* @default process.env.GITHUB_STEP_SUMMARY
*/
outputPath: string | undefined;
/**
* Configuration for generating permalink URLs to source files in the GitHub repository.
*
* When all three values are available (either from this config or the defaults picked from environment variables), test names in the summary will link to the relevant source lines.
*/
fileLinks: {
/**
* The GitHub repository in `owner/repo` format.
*
* @default process.env.GITHUB_REPOSITORY
*/
repository?: string | undefined;
/**
* The commit SHA to use in permalink URLs.
*
* @default process.env.GITHUB_SHA
*/
commitHash?: string | undefined;
/**
* The absolute path to the root of the repository on disk.
*
* This value is used to compute relative file paths for the permalink URLs.
*
* @default process.env.GITHUB_WORKSPACE
*/
workspacePath?: string | undefined;
};
}
type ResolvedOptions = Required;
declare class GithubActionsReporter implements Reporter {
ctx: Vitest;
options: ResolvedOptions;
constructor(options?: GithubActionsReporterOptions);
onInit(ctx: Vitest): void;
onTestCaseAnnotate(testCase: TestCase, annotation: TestAnnotation): void;
onTestRunEnd(testModules: ReadonlyArray, unhandledErrors: ReadonlyArray): void;
}
interface HTMLOptions {
/**
* Directory used as the report artifact root.
*
* The report entry is written to `/index.html` and the UI
* implementation files live under `/ui/`. By default this is the
* shared `.vitest` artifact directory.
*
* @default '.vitest'
*/
outputDir?: string;
/**
* Inline report assets, metadata, and attachments into the generated HTML file.
*
* @default false
*/
singleFile?: boolean;
}
type Status = "passed" | "failed" | "skipped" | "pending" | "todo" | "disabled";
type Milliseconds = number;
interface Callsite {
line: number;
column: number;
}
interface JsonAssertionResult {
ancestorTitles: Array;
fullName: string;
status: Status;
title: string;
meta: TaskMeta;
duration?: Milliseconds | null;
failureMessages: Array | null;
location?: Callsite | null;
tags: string[];
benchmarks: TestBenchmark[];
}
interface JsonTestResult {
message: string;
name: string;
status: "failed" | "passed";
startTime: number;
endTime: number;
assertionResults: Array;
}
interface JsonTestResults {
numFailedTests: number;
numFailedTestSuites: number;
numPassedTests: number;
numPassedTestSuites: number;
numPendingTests: number;
numPendingTestSuites: number;
numTodoTests: number;
numTotalTests: number;
numTotalTestSuites: number;
startTime: number;
success: boolean;
testResults: Array;
snapshot: SnapshotSummary;
coverageMap?: CoverageMap | null | undefined;
}
interface JsonOptions {
outputFile?: string;
/**
* Print the report to stdout instead of writing it to a file.
* Ignored when {@link outputFile} is set.
* @default false
*/
stdout?: boolean;
/** @experimental */
filterMeta?: (key: string, value: unknown) => unknown;
}
declare class JsonReporter implements Reporter {
start: number;
ctx: Vitest;
options: JsonOptions;
coverageMap?: CoverageMap;
constructor(options: JsonOptions);
onInit(ctx: Vitest): void;
onCoverage(coverageMap: unknown): void;
onTestRunEnd(testModules: ReadonlyArray): Promise;
}
interface ClassnameTemplateVariables {
/** Relative path from the root (e.g. `src/foo.test.ts`) */
filename: string;
/** Absolute file path */
filepath: string;
/** File basename without directory (e.g. `foo.test.ts`) */
basename: string;
/** Ancestor describe block names joined by {@link JUnitOptions.ancestorSeparator} */
classname: string;
/** Leaf test title (the string passed to `it`/`test`) */
title: string;
/** Top-level describe block name, or empty string when the test has no enclosing describe */
suitename: string;
/** Vitest project name */
displayName: string;
}
interface SuiteNameTemplateVariables {
/** Absolute file path */
filepath: string;
/** Relative path from the root (e.g. `src/foo.test.ts`) */
filename: string;
/** File basename without directory (e.g. `foo.test.ts`) */
basename: string;
/** Vitest project name */
displayName: string;
/**
* The name of the first top-level `describe` block in the file.
* Falls back to the file basename when the file has no top-level describe.
*/
title: string;
}
interface JUnitOptions {
outputFile?: string;
/**
* Print the report to stdout instead of writing it to a file.
* Ignored when {@link outputFile} is set.
* @default false
*/
stdout?: boolean;
/**
* Template for the `classname` attribute of ``.
*
* Can be a template string or a function.
*
* Supported placeholders:
* - `{filename}` – relative path from root (e.g. `src/foo.test.ts`)
* - `{filepath}` – absolute file path
* - `{basename}` – file name without directory (e.g. `foo.test.ts`)
* - `{classname}` – ancestor describe names joined by {@link ancestorSeparator}
* - `{title}` – leaf test title
* - `{suitename}` – top-level describe block name
* - `{displayName}` – Vitest project name
*
* @default relative file path from root
*/
classnameTemplate?: string | ((classnameVariables: ClassnameTemplateVariables) => string);
/**
* Template for the `name` attribute of ``.
*
* Can be a template string or a function. Supports the same placeholders as
* {@link classnameTemplate}.
*
* When not set the full test title including ancestor describe hierarchy is used
* (current default behaviour, e.g. `outer > inner > test name`).
*/
titleTemplate?: string | ((titleVariables: ClassnameTemplateVariables) => string);
/**
* Template for the `name` attribute of ``.
*
* Can be a template string or a function.
*
* Supported placeholders:
* - `{title}` – first top-level describe name (falls back to file basename)
* - `{filename}` – relative path from root
* - `{filepath}` – absolute file path
* - `{basename}` – file basename
* - `{displayName}` – Vitest project name
*
* When not set the relative file path from root is used (current default behaviour).
*/
suiteNameTemplate?: string | ((suiteNameVariables: SuiteNameTemplateVariables) => string);
/**
* Separator used to join ancestor describe block names when building the
* `{classname}` template variable (and the default testcase name when
* {@link titleTemplate} is not set).
*
* @default ' > '
*/
ancestorSeparator?: string;
suiteName?: string;
/**
* Write and for console output
* @default true
*/
includeConsoleOutput?: boolean;
/**
* Add attribute (validated on CIRCLE CI and GitLab CI)
* @default false
*/
addFileAttribute?: boolean;
/**
* Hostname to use in the report. By default, it uses os.hostname()
*/
hostname?: string;
/**
* Include stack traces in test failure reports.
* @default true
*/
stackTrace?: boolean;
}
/**
* Internal task type that carries pre-computed template metadata.
* The three underscore-prefixed fields are set by {@link flattenTasks} and
* consumed only within the reporter. They are deliberately not part of the
* public `Task` interface.
*/
type TaskWithMeta = Task & {
/** Original leaf test title before hierarchy prefix was prepended */
_leafName?: string;
/** Ancestor describe names joined by the active separator */
_classname?: string;
/** Top-level describe block name */
_suitename?: string;
};
/**
* Runtime additions on top of {@link SerializedError}: `type` is set by
* {@link state.catchError}, `VITEST_TEST_PATH` by the runtime error catcher.
*/
type UnhandledError = SerializedError & {
type?: string;
VITEST_TEST_PATH?: string;
};
declare class JUnitReporter implements Reporter {
private ctx;
private reportFile?;
private baseLog;
private logger;
private _timeStart;
private fileFd?;
private options;
constructor(options: JUnitOptions);
onInit(ctx: Vitest): Promise;
writeElement(name: string, attrs: Record, children: () => Promise): Promise;
writeLogs(task: Task, type: "err" | "out"): Promise;
writeSystemOut(task: Task): Promise;
private applyTemplate;
writeTasks(tasks: TaskWithMeta[], filename: string, fileAbsPath: string): Promise;
private resolveSuiteNameTemplate;
private writeErrorElement;
private writeUnhandledErrorsTestsuite;
onTestRunEnd(testModules: ReadonlyArray, unhandledErrors?: ReadonlyArray): Promise;
}
declare class DotReporter extends BaseReporter {
private renderer?;
private tests;
private finishedTests;
onInit(ctx: Vitest): void;
printTestModule(): void;
onTestRunStart(_specifications: ReadonlyArray): void;
onWatcherRerun(files: string[], trigger?: string): void;
onTestRunEnd(testModules: ReadonlyArray, unhandledErrors: ReadonlyArray, reason: TestRunEndReason): void;
onTestModuleCollected(module: TestModule): void;
onTestCaseReady(test: TestCase): void;
onTestCaseResult(test: TestCase): void;
onTestModuleEnd(testModule: TestModule): void;
private createSummary;
}
declare class HangingProcessReporter implements Reporter {
whyRunning: (() => void) | undefined;
onInit(): Promise;
onProcessTimeout(): void;
}
declare class MinimalReporter extends DefaultReporter {
renderSucceed: boolean;
constructor(options?: DefaultReporterOptions);
onInit(ctx: Vitest): void;
onTestRunStart(specifications: ReadonlyArray): void;
protected printTestModule(testModule: TestModule): void;
protected printTestCase(moduleState: TestModuleState, test: TestCase): void;
}
declare class TapReporter implements Reporter {
protected ctx: Vitest;
private logger;
onInit(ctx: Vitest): void;
static getComment(task: Task): string;
private logErrorDetails;
protected logTasks(tasks: Task[]): void;
onTestRunEnd(testModules: ReadonlyArray): void;
}
declare class TapFlatReporter extends TapReporter {
onInit(ctx: Vitest): void;
onTestRunEnd(testModules: ReadonlyArray): void;
}
declare class TreeReporter extends DefaultReporter {
protected verbose: boolean;
renderSucceed: boolean;
}
declare class VerboseReporter extends DefaultReporter {
protected verbose: boolean;
renderSucceed: boolean;
printTestModule(_module: TestModule): void;
onTestCaseResult(test: TestCase): void;
}
declare const ReportersMap: {
default: typeof DefaultReporter;
agent: typeof MinimalReporter;
minimal: typeof MinimalReporter;
blob: typeof BlobReporter;
verbose: typeof VerboseReporter;
dot: typeof DotReporter;
json: typeof JsonReporter;
tap: typeof TapReporter;
"tap-flat": typeof TapFlatReporter;
junit: typeof JUnitReporter;
tree: typeof TreeReporter;
"hanging-process": typeof HangingProcessReporter;
"github-actions": typeof GithubActionsReporter;
};
type BuiltinReporters = keyof typeof ReportersMap;
interface BuiltinReporterOptions {
default: DefaultReporterOptions;
minimal: DefaultReporterOptions;
agent: DefaultReporterOptions;
verbose: DefaultReporterOptions;
dot: BaseOptions;
tree: BaseOptions;
json: JsonOptions;
blob: BlobOptions;
tap: never;
"tap-flat": never;
junit: JUnitOptions;
"hanging-process": never;
html: HTMLOptions;
"github-actions": GithubActionsReporterOptions;
}
interface TestSequencer {
/**
* Slicing tests into shards. Will be run before `sort`.
* Only run, if `shard` is defined.
*/
shard: (files: TestSpecification[]) => Awaitable;
sort: (files: TestSpecification[]) => Awaitable;
}
interface TestSequencerConstructor {
new (ctx: Vitest): TestSequencer;
}
interface BenchmarkUserOptions {
enabled?: boolean;
/**
* Include globs for benchmark test files
*
* @default ['**\/*.{bench,benchmark}.?(c|m)[jt]s?(x)']
*/
include?: string[];
/**
* Exclude globs for benchmark test files
*
* @default ['**\/node_modules/**', '**\/.git/**']
*/
exclude?: string[];
/**
* Include globs for in-source benchmark test files
*
* @default []
*/
includeSource?: string[];
/**
* Include `samples` array of benchmark results for API or custom reporter usages.
* This is disabled by default to reduce memory usage.
* @default false
*/
retainSamples?: boolean;
/**
* The benchmark provider that executes registered benchmarks and produces
* their results. Provide a path to a module whose default export implements
* `BenchmarkProvider`. The path is resolved relative to the project
* root. If not specified, the built-in provider is used.
*
* @experimental
*/
provider?: string;
/**
* Disable warnings when a benchmark accesses module export getters too many times.
* @default false
*/
suppressExportGetterWarnings?: boolean;
}
type ResolvedBenchmarkOptions = Omit, "provider"> & {
provider?: string;
};
type BuiltinEnvironment = "node" | "jsdom" | "happy-dom" | "edge-runtime";
type VitestEnvironment = BuiltinEnvironment | (string & Record);
type CSSModuleScopeStrategy = "stable" | "scoped" | "non-scoped";
type ApiConfig = Pick & {
/**
* Allow any write operations from the API server.
*
* @default false if `api.host` is exposed to network, true otherwise
*/
allowWrite?: boolean;
/**
* Allow running test files via the API.
* If `api.host` is exposed to network and `allowWrite` is true,
* anyone connected to the API server can run arbitrary code on your machine.
*
* @default false if `api.host` is exposed to network, true otherwise
*/
allowExec?: boolean;
};
type ResolvedApiConfig = ApiConfig & {
token: string;
tokenCreated: boolean;
};
interface EnvironmentOptions {
/**
* jsdom options.
*/
jsdom?: JSDOMOptions;
happyDOM?: HappyDOMOptions;
[x: string]: unknown;
}
/**
* @deprecated
*/
type VitestRunMode = "test";
interface ProjectName {
label: string;
color?: LabelColor;
}
interface SequenceOptions {
/**
* Class that handles sorting and sharding algorithm.
* If you only need to change sorting, you can extend
* your custom sequencer from `BaseSequencer` from `vitest/node`.
* @default BaseSequencer
*/
sequencer?: TestSequencerConstructor;
/**
* Controls the order in which this project runs its tests when using multiple [projects](/guide/projects).
*
* - Projects with the same group order number will run together, and groups are run from lowest to highest.
* - If you don’t set this option, all projects run in parallel.
* - If several projects use the same group order, they will run at the same time.
* @default 0
*/
groupOrder?: number;
/**
* Should files and tests run in random order.
* @default false
*/
shuffle?: boolean | {
/**
* Should files run in random order. Long running tests will not start
* earlier if you enable this option.
* @default false
*/
files?: boolean;
/**
* Should tests run in random order.
* @default false
*/
tests?: boolean;
};
/**
* Should tests run in parallel.
* @default false
*/
concurrent?: boolean;
/**
* Defines how setup files should be ordered
* - 'parallel' will run all setup files in parallel
* - 'list' will run all setup files in the order they are defined in the config file
* @default 'list'
*/
setupFiles?: SequenceSetupFiles;
/**
* Seed for the random number generator.
* @default Date.now()
*/
seed?: number;
/**
* Defines how hooks should be ordered
* - `stack` will order "after" hooks in reverse order, "before" hooks will run sequentially
* - `list` will order hooks in the order they are defined
* - `parallel` will run hooks in a single group in parallel
* @default 'stack'
*/
hooks?: SequenceHooks;
}
type DepsOptimizationOptions = Omit & {
enabled?: boolean;
};
interface DepsOptions {
/**
* Enable dependency optimization. This can improve the performance of your tests.
*/
optimizer?: Partial>;
web?: {
/**
* Should Vitest process assets (.png, .svg, .jpg, etc) files and resolve them like Vite does in the browser.
*
* These module will have a default export equal to the path to the asset, if no query is specified.
*
* **At the moment, this option only works with `{ pool: 'vmThreads' }`.**
*
* @default true
*/
transformAssets?: boolean;
/**
* Should Vitest process CSS (.css, .scss, .sass, etc) files and resolve them like Vite does in the browser.
*
* If CSS files are disabled with `css` options, this option will just silence UNKNOWN_EXTENSION errors.
*
* **At the moment, this option only works with `{ pool: 'vmThreads' }`.**
*
* @default true
*/
transformCss?: boolean;
/**
* Regexp pattern to match external files that should be transformed.
*
* By default, files inside `node_modules` are externalized and not transformed.
*
* **At the moment, this option only works with `{ pool: 'vmThreads' }`.**
*
* @default []
*/
transformGlobPattern?: RegExp | RegExp[];
};
/**
* Interpret CJS module's default as named exports
*
* @default true
*/
interopDefault?: boolean;
/**
* A list of directories relative to the config file that should be treated as module directories.
*
* @default ['node_modules']
*/
moduleDirectories?: string[];
}
type InlineReporter = Reporter;
type ReporterName = BuiltinReporters | "html" | (string & {});
type ReporterWithOptions = Name extends keyof BuiltinReporterOptions ? BuiltinReporterOptions[Name] extends never ? [Name, object] : [Name, Partial] : [Name, Record];
interface ResolveSnapshotPathHandlerContext {
config: SerializedConfig;
}
type ResolveSnapshotPathHandler = (testPath: string, snapExtension: string, context: ResolveSnapshotPathHandlerContext) => string;
type BuiltinPool = "browser" | "threads" | "forks" | "vmThreads" | "vmForks" | "typescript";
type Pool = BuiltinPool | (string & {});
interface InlineConfig {
/**
* Name of the project. Will be used to display in the reporter.
*/
name?: string | ProjectName;
/**
* Benchmark options.
*
* @default {}
*/
benchmark?: BenchmarkUserOptions;
/**
* A list of [glob patterns](https://superchupu.dev/tinyglobby/comparison) that match your test files.
*
* @default ['**\/*.{test,spec}.?(c|m)[jt]s?(x)']
* @see {@link https://vitest.dev/config/include}
*/
include?: string[];
/**
* Exclude globs for test files
* @default ['**\/node_modules/**', '**\/.git/**']
*/
exclude?: string[];
/**
* Include globs for in-source test files
*
* @default []
*/
includeSource?: string[];
/**
* Handling for dependencies inlining or externalizing
*
*/
deps?: DepsOptions;
server?: {
deps?: ServerDepsOptions;
debug?: {
/**
* The folder where Vitest stores the contents of transformed
* test files that can be inspected manually.
*
* If `true`, Vitest dumps the files in `.vitest-dump` folder relative to the root of the project.
*
* You can also use `VITEST_DEBUG_DUMP` env variable to enable this.
*/
dump?: string | true;
/**
* If dump is enabled, should Vitest load the files from there instead of transforming them.
*
* You can also use `VITEST_DEBUG_LOAD_DUMP` env variable to enable this.
*/
load?: boolean;
};
};
/**
* Base directory to scan for the test files
*
* @default `config.root`
*/
dir?: string;
/**
* Register apis globally
*
* @default false
*/
globals?: boolean;
/**
* Inject CommonJS module variables (`module`, `exports`, `require`,
* `__filename`, `__dirname`) into every module processed by Vitest.
*
* When disabled, ES modules no longer have access to CommonJS variables,
* matching how the code runs outside of Vitest. Modules detected to be
* CommonJS keep these variables because they are part of the module scope.
* The module type is detected the same way Node.js does it: the file
* extension wins, then the `type` field in the nearest package.json,
* then the presence of ESM syntax in the file.
*
* This option doesn't affect externalized modules which are always
* executed by the native runtime.
*
* @default true
*/
injectCjsGlobals?: boolean;
/**
* Running environment
*
* Supports 'node', 'jsdom', 'happy-dom', 'edge-runtime'
*
* If used unsupported string, will try to load the package `vitest-environment-${env}`
*
* @default 'node'
*/
environment?: VitestEnvironment;
/**
* Environment options.
*/
environmentOptions?: EnvironmentOptions;
/**
* Run tests in an isolated environment. This option has no effect on vmThreads pool.
*
* Disabling this option improves performance if your code doesn't rely on side effects.
*
* @default true
*/
isolate?: boolean;
/**
* Pass additional arguments to `node` process when spawning the worker.
*
* See [Command-line API | Node.js](https://nodejs.org/docs/latest/api/cli.html) for more information.
*
* Set to `process.execArgv` to pass all arguments of the current process.
*
* Be careful when using, it as some options may crash worker, e.g. --prof, --title. See https://github.com/nodejs/node/issues/41103
*
* @default [] // no execution arguments are passed
*/
execArgv?: string[];
/**
* Specifies the memory limit for `worker_thread` or `child_process` before they are recycled.
* If you see memory leaks, try to tinker this value.
*/
vmMemoryLimit?: string | number;
/**
* Pool used to run tests in.
*
* Supports 'threads', 'forks', 'vmThreads', 'vmForks'
*
* @default 'forks'
*/
pool?: Exclude | PoolRunnerInitializer;
/**
* Maximum number or percentage of workers to run tests in.
*/
maxWorkers?: number | string;
/**
* Should all test files run in parallel. Doesn't affect tests running in the same file.
* Setting this to `false` will override `maxWorkers` option to `1`.
*
* @default true
*/
fileParallelism?: boolean;
/**
* Options for projects.
*
* When a project is referenced as a config file (or a directory with one) and
* that config declares `projects` itself, it becomes a container: it doesn't
* run tests, only provides the projects it declares. Inline configurations
* cannot declare `projects`.
*/
projects?: TestProjectConfiguration[];
/**
* Let inline projects that don't modify the Vite config reuse the Vite
* server of the config that declares them. Instead of resolving a new
* Vite config and creating a new server per project, such projects share
* the server and its transform cache.
*
* A project still gets its own server when it defines Vite-level options
* (`plugins`, `resolve`, ...) or test options that affect the
* Vite config: `alias`, `browser`, `css`, `deps.moduleDirectories`,
* `deps.optimizer`, `mode`, `root`,
* or when `extends` doesn't point to the declaring config.
*
* This option is only respected in the root configuration.
* @default true
*/
sharedViteServer?: boolean;
/**
* Update snapshot
*
* @default false
*/
update?: boolean | "all" | "new" | "none";
/**
* Watch mode
*
* @default !process.env.CI && process.stdin.isTTY && !isAgent
*/
watch?: boolean;
/**
* Project root
*
* @default process.cwd()
*/
root?: string;
/**
* Custom reporter for output. Can contain one or more built-in reporter names, reporter instances,
* and/or paths to custom reporters.
*
* @default ['default'] (or ['default', 'github-actions'] when `process.env.GITHUB_ACTIONS === 'true'`)
*/
reporters?: Arrayable | ((ReporterName | InlineReporter) | [ReporterName] | ReporterWithOptions)[];
/**
* Write test results to a file when the --reporter=json` or `--reporter=junit` option is also specified.
* Also definable individually per reporter by using an object instead.
*/
outputFile?: string | (Partial