@vitest/runner 2.0.5 → 2.1.0-beta.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { VitestRunner } from './types.js';
 export { CancelReason, VitestRunnerConfig, VitestRunnerConstructor, VitestRunnerImportSource } from './types.js';
-import { T as Task, F as File, d as SuiteAPI, e as TestAPI, f as SuiteCollector, g as CustomAPI, B as BeforeAllListener, A as AfterAllListener, h as BeforeEachListener, i as AfterEachListener, j as TaskHook, O as OnTestFailedHandler, k as OnTestFinishedHandler, a as Test, C as Custom, S as Suite, l as SuiteHooks } from './tasks-zB5uPauP.js';
-export { D as DoneCallback, L as ExtendedContext, w as Fixture, v as FixtureFn, u as FixtureOptions, x as Fixtures, y as HookCleanupCallback, H as HookListener, I as InferFixturesTypes, R as RunMode, G as RuntimeContext, M as SequenceHooks, N as SequenceSetupFiles, E as SuiteFactory, n as TaskBase, K as TaskContext, z as TaskCustomOptions, p as TaskMeta, o as TaskPopulated, q as TaskResult, r as TaskResultPack, m as TaskState, J as TestContext, s as TestFunction, t as TestOptions, U as Use } from './tasks-zB5uPauP.js';
+import { T as Task, F as File, d as SuiteAPI, e as TestAPI, f as SuiteCollector, g as CustomAPI, B as BeforeAllListener, A as AfterAllListener, h as BeforeEachListener, i as AfterEachListener, j as TaskHook, O as OnTestFailedHandler, k as OnTestFinishedHandler, a as Test, C as Custom, S as Suite, l as SuiteHooks } from './tasks-C13WjyUB.js';
+export { D as DoneCallback, L as ExtendedContext, w as Fixture, v as FixtureFn, u as FixtureOptions, x as Fixtures, y as HookCleanupCallback, H as HookListener, I as InferFixturesTypes, R as RunMode, G as RuntimeContext, M as SequenceHooks, N as SequenceSetupFiles, E as SuiteFactory, n as TaskBase, K as TaskContext, z as TaskCustomOptions, p as TaskMeta, o as TaskPopulated, q as TaskResult, r as TaskResultPack, m as TaskState, J as TestContext, s as TestFunction, t as TestOptions, U as Use } from './tasks-C13WjyUB.js';
 import { Awaitable } from '@vitest/utils';
 export { processError } from '@vitest/utils/error';
 import '@vitest/utils/diff';

package/dist/index.js

@@ -307,13 +307,20 @@ const it = test;
 let runner;
 let defaultSuite;
 let currentTestFilepath;
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(`Vitest failed to find ${message}. This is a bug in Vitest. Please, open an issue with reproduction.`);
+  }
+}
 function getDefaultSuite() {
+  assert(defaultSuite, "the default suite");
   return defaultSuite;
 }
 function getTestFilepath() {
   return currentTestFilepath;
 }
 function getRunner() {
+  assert(runner, "the runner");
   return runner;
 }
 function createDefaultSuite(runner2) {
@@ -333,7 +340,9 @@ function clearCollectorContext(filepath, currentRunner) {
   collectorContext.currentSuite = defaultSuite;
 }
 function getCurrentSuite() {
-  return collectorContext.currentSuite || defaultSuite;
+  const currentSuite = collectorContext.currentSuite || defaultSuite;
+  assert(currentSuite, "the current suite");
+  return currentSuite;
 }
 function createSuiteHooks() {
   return {
@@ -518,7 +527,7 @@ function createSuiteCollector(name, factory = () => {
 function createSuite() {
   function suiteFn(name, factoryOrOptions, optionsOrFactory = {}) {
     const mode = this.only ? "only" : this.skip ? "skip" : this.todo ? "todo" : "run";
-    const currentSuite = getCurrentSuite();
+    const currentSuite = collectorContext.currentSuite || defaultSuite;
     let { options, handler: factory } = parseArguments(
       factoryOrOptions,
       optionsOrFactory

package/dist/{tasks-zB5uPauP.d.ts → tasks-C13WjyUB.d.ts}

@@ -23,74 +23,216 @@ interface FixtureItem extends FixtureOptions {
 type RunMode = 'run' | 'skip' | 'only' | 'todo';
 type TaskState = RunMode | 'pass' | 'fail';
 interface TaskBase {
+    /**
+     * Unique task identifier. Based on the file id and the position of the task.
+     * The id of the file task is based on the file path relative to root and project name.
+     * It will not change between runs.
+     * @example `1201091390`, `1201091390_0`, `1201091390_0_1`
+     */
     id: string;
+    /**
+     * Task name provided by the user. If no name was provided, it will be an empty string.
+     */
     name: string;
+    /**
+     * Task mode.
+     * - **skip**: task is skipped
+     * - **only**: only this task and other tasks with `only` mode will run
+     * - **todo**: task is marked as a todo, alias for `skip`
+     * - **run**: task will run or already ran
+     */
     mode: RunMode;
+    /**
+     * Custom metadata for the task. JSON reporter will save this data.
+     */
     meta: TaskMeta;
+    /**
+     * Whether the task was produced with `.each()` method.
+     */
     each?: boolean;
+    /**
+     * Whether the task should run concurrently with other tasks.
+     */
     concurrent?: boolean;
+    /**
+     * Whether the tasks of the suite run in a random order.
+     */
     shuffle?: boolean;
+    /**
+     * Suite that this task is part of. File task or the global suite will have no parent.
+     */
     suite?: Suite;
+    /**
+     * Result of the task. Suite and file tasks will only have the result if there
+     * was an error during collection or inside `afterAll`/`beforeAll`.
+     */
     result?: TaskResult;
+    /**
+     * The amount of times the task should be retried if it fails.
+     * @default 0
+     */
     retry?: number;
+    /**
+     * The amount of times the task should be repeated after the successful run.
+     * If the task fails, it will not be retried unless `retry` is specified.
+     * @default 0
+     */
     repeats?: number;
+    /**
+     * Location of the task in the file. This field is populated only if
+     * `includeTaskLocation` option is set. It is generated by calling `new Error`
+     * and parsing the stack trace, so the location might differ depending on the runtime.
+     */
     location?: {
         line: number;
         column: number;
     };
 }
 interface TaskPopulated extends TaskBase {
+    /**
+     * File task. It's the root task of the file.
+     */
     file: File;
+    /**
+     * Whether the task was skipped by calling `t.skip()`.
+     */
     pending?: boolean;
-    result?: TaskResult;
+    /**
+     * Whether the task should succeed if it fails. If the task fails, it will be marked as passed.
+     */
     fails?: boolean;
+    /**
+     * Hooks that will run if the task fails. The order depends on the `sequence.hooks` option.
+     */
     onFailed?: OnTestFailedHandler[];
+    /**
+     * Hooks that will run after the task finishes. The order depends on the `sequence.hooks` option.
+     */
     onFinished?: OnTestFinishedHandler[];
     /**
      * Store promises (from async expects) to wait for them before finishing the test
      */
     promises?: Promise<any>[];
 }
+/**
+ * Custom metadata that can be used in reporters.
+ */
 interface TaskMeta {
 }
+/**
+ * The result of calling a task.
+ */
 interface TaskResult {
+    /**
+     * State of the task. Inherits the `task.mode` during collection.
+     * When the task has finished, it will be changed to `pass` or `fail`.
+     * - **pass**: task ran successfully
+     * - **fail**: task failed
+     */
     state: TaskState;
+    /**
+     * Errors that occurred during the task execution. It is possible to have several errors
+     * if `expect.soft()` failed multiple times.
+     */
+    errors?: ErrorWithDiff[];
+    /**
+     * How long in milliseconds the task took to run.
+     */
     duration?: number;
+    /**
+     * Time in milliseconds when the task started running.
+     */
     startTime?: number;
+    /**
+     * Heap size in bytes after the task finished.
+     * Only available if `logHeapUsage` option is set and `process.memoryUsage` is defined.
+     */
     heap?: number;
-    errors?: ErrorWithDiff[];
-    htmlError?: string;
+    /**
+     * State of related to this task hooks. Useful during reporting.
+     */
     hooks?: Partial<Record<keyof SuiteHooks, TaskState>>;
+    /**
+     * The amount of times the task was retried. The task is retried only if it
+     * failed and `retry` option is set.
+     */
     retryCount?: number;
+    /**
+     * The amount of times the task was repeated. The task is repeated only if
+     * `repeats` option is set. This number also contains `retryCount`.
+     */
     repeatCount?: number;
 }
+/**
+ * The tuple representing a single task update.
+ * Usually reported after the task finishes.
+ */
 type TaskResultPack = [
+    /**
+     * Unique task identifier from `task.id`.
+     */
     id: string,
+    /**
+     * The result of running the task from `task.result`.
+     */
     result: TaskResult | undefined,
+    /**
+     * Custom metadata from `task.meta`.
+     */
     meta: TaskMeta
 ];
 interface Suite extends TaskBase {
-    file: File;
     type: 'suite';
+    /**
+     * File task. It's the root task of the file.
+     */
+    file: File;
+    /**
+     * An array of tasks that are part of the suite.
+     */
     tasks: Task[];
 }
 interface File extends Suite {
+    /**
+     * The name of the pool that the file belongs to.
+     * @default 'forks'
+     */
     pool?: string;
+    /**
+     * The path to the file in UNIX format.
+     */
     filepath: string;
+    /**
+     * The name of the workspace project the file belongs to.
+     */
     projectName: string | undefined;
+    /**
+     * The time it took to collect all tests in the file.
+     * This time also includes importing all the file dependencies.
+     */
     collectDuration?: number;
+    /**
+     * The time it took to import the setup file.
+     */
     setupDuration?: number;
     /**
      * Whether the file is initiated without running any tests.
+     * This is done to populate state on the server side by Vitest.
      */
     local?: boolean;
 }
 interface Test<ExtraContext = object> extends TaskPopulated {
     type: 'test';
+    /**
+     * Test context that will be passed to the test function.
+     */
     context: TaskContext<Test> & ExtraContext & TestContext;
 }
 interface Custom<ExtraContext = object> extends TaskPopulated {
     type: 'custom';
+    /**
+     * Task context that will be passed to the test function.
+     */
     context: TaskContext<Custom> & ExtraContext & TestContext;
 }
 type Task = Test | Suite | Custom | File;
@@ -156,7 +298,7 @@ interface TestOptions {
      */
     retry?: number;
     /**
-     * How many times the test will run.
+     * How many times the test will run again.
      * Only inner tests will repeat if set on `describe()`, nested `describe()` will inherit parent's repeat by default.
      *
      * @default 0
@@ -198,11 +340,7 @@ type CustomAPI<ExtraContext = object> = ChainableTestAPI<ExtraContext> & Extende
         [K in keyof T | keyof ExtraContext]: K extends keyof T ? T[K] : K extends keyof ExtraContext ? ExtraContext[K] : never;
     }>;
 };
-type TestAPI<ExtraContext = object> = ChainableTestAPI<ExtraContext> & ExtendedAPI<ExtraContext> & {
-    extend: <T extends Record<string, any> = object>(fixtures: Fixtures<T, ExtraContext>) => TestAPI<{
-        [K in keyof T | keyof ExtraContext]: K extends keyof T ? T[K] : K extends keyof ExtraContext ? ExtraContext[K] : never;
-    }>;
-};
+type TestAPI<ExtraContext = object> = CustomAPI<ExtraContext>;
 interface FixtureOptions {
     /**
      * Whether to automatically set up current fixture, even though it's not being used in tests.
@@ -255,15 +393,23 @@ interface SuiteHooks<ExtraContext = object> {
     afterEach: AfterEachListener<ExtraContext>[];
 }
 interface TaskCustomOptions extends TestOptions {
-    concurrent?: boolean;
-    sequential?: boolean;
-    skip?: boolean;
-    only?: boolean;
-    todo?: boolean;
-    fails?: boolean;
+    /**
+     * Whether the task was produced with `.each()` method.
+     */
     each?: boolean;
+    /**
+     * Custom metadata for the task that will be assigned to `task.meta`.
+     */
     meta?: Record<string, unknown>;
+    /**
+     * Task fixtures.
+     */
     fixtures?: FixtureItem[];
+    /**
+     * Function that will be called when the task is executed.
+     * If nothing is provided, the runner will try to get the function using `getFn(task)`.
+     * If the runner cannot find the function, the task will be marked as failed.
+     */
     handler?: (context: TaskContext<Custom>) => Awaitable<void>;
 }
 interface SuiteCollector<ExtraContext = object> {
@@ -300,6 +446,7 @@ interface TaskContext<Task extends Custom | Test = Custom | Test> {
     onTestFinished: (fn: OnTestFinishedHandler) => void;
     /**
      * Mark tests as skipped. All execution after this call will be skipped.
+     * This function throws an error, so make sure you are not catching it accidentally.
      */
     skip: () => void;
 }

package/dist/types.d.ts

@@ -1,8 +1,11 @@
-import { M as SequenceHooks, N as SequenceSetupFiles, F as File, T as Task, S as Suite, r as TaskResultPack, a as Test, C as Custom, K as TaskContext, L as ExtendedContext } from './tasks-zB5uPauP.js';
-export { A as AfterAllListener, i as AfterEachListener, B as BeforeAllListener, h as BeforeEachListener, g as CustomAPI, D as DoneCallback, w as Fixture, v as FixtureFn, u as FixtureOptions, x as Fixtures, y as HookCleanupCallback, H as HookListener, I as InferFixturesTypes, O as OnTestFailedHandler, k as OnTestFinishedHandler, R as RunMode, G as RuntimeContext, d as SuiteAPI, f as SuiteCollector, E as SuiteFactory, l as SuiteHooks, n as TaskBase, z as TaskCustomOptions, j as TaskHook, p as TaskMeta, o as TaskPopulated, q as TaskResult, m as TaskState, e as TestAPI, J as TestContext, s as TestFunction, t as TestOptions, U as Use } from './tasks-zB5uPauP.js';
+import { M as SequenceHooks, N as SequenceSetupFiles, F as File, T as Task, a as Test, C as Custom, S as Suite, r as TaskResultPack, K as TaskContext, L as ExtendedContext } from './tasks-C13WjyUB.js';
+export { A as AfterAllListener, i as AfterEachListener, B as BeforeAllListener, h as BeforeEachListener, g as CustomAPI, D as DoneCallback, w as Fixture, v as FixtureFn, u as FixtureOptions, x as Fixtures, y as HookCleanupCallback, H as HookListener, I as InferFixturesTypes, O as OnTestFailedHandler, k as OnTestFinishedHandler, R as RunMode, G as RuntimeContext, d as SuiteAPI, f as SuiteCollector, E as SuiteFactory, l as SuiteHooks, n as TaskBase, z as TaskCustomOptions, j as TaskHook, p as TaskMeta, o as TaskPopulated, q as TaskResult, m as TaskState, e as TestAPI, J as TestContext, s as TestFunction, t as TestOptions, U as Use } from './tasks-C13WjyUB.js';
 import { DiffOptions } from '@vitest/utils/diff';
 import '@vitest/utils';
 
+/**
+ * This is a subset of Vitest config that's required for the runner to work.
+ */
 interface VitestRunnerConfig {
     root: string;
     setupFiles: string[];
@@ -65,7 +68,7 @@ interface VitestRunner {
     /**
      * When the task has finished running, but before cleanup hooks are called
      */
-    onTaskFinished?: (test: Task) => unknown;
+    onTaskFinished?: (test: Test | Custom) => unknown;
     /**
      * Called after result and state are set.
      */
@@ -108,7 +111,7 @@ interface VitestRunner {
      */
     onAfterRunFiles?: (files: File[]) => unknown;
     /**
-     * Called when new context for a test is defined. Useful, if you want to add custom properties to the context.
+     * Called when new context for a test is defined. Useful if you want to add custom properties to the context.
      * If you only want to define custom context, consider using "beforeAll" in "setupFiles" instead.
      *
      * This method is called for both "test" and "custom" handlers.
@@ -117,7 +120,7 @@ interface VitestRunner {
      */
     extendTaskContext?: <T extends Test | Custom>(context: TaskContext<T>) => ExtendedContext<T>;
     /**
-     * Called, when files are imported. Can be called in two situations: when collecting tests and when importing setup files.
+     * Called when test and setup files are imported. Can be called in two situations: when collecting tests and when importing setup files.
      */
     importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
     /**

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
-import { S as Suite, F as File, T as Task, a as Test, C as Custom } from './tasks-zB5uPauP.js';
-export { b as ChainableFunction, c as createChainable } from './tasks-zB5uPauP.js';
+import { S as Suite, F as File, T as Task, a as Test, C as Custom } from './tasks-C13WjyUB.js';
+export { b as ChainableFunction, c as createChainable } from './tasks-C13WjyUB.js';
 import { Arrayable } from '@vitest/utils';
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vitest/runner",
   "type": "module",
-  "version": "2.0.5",
+  "version": "2.1.0-beta.1",
   "description": "Vitest test runner",
   "license": "MIT",
   "funding": "https://opencollective.com/vitest",
@@ -39,7 +39,7 @@
   ],
   "dependencies": {
     "pathe": "^1.1.2",
-    "@vitest/utils": "2.0.5"
+    "@vitest/utils": "2.1.0-beta.1"
   },
   "scripts": {
     "build": "rimraf dist && rollup -c",