@vitest-agent/mcp 1.0.1 → 1.2.0

package/public/vendor/vitest-docs/api/advanced/reporters.md

@@ -1,342 +0,0 @@
-# Reporters
-
-::: warning
-This is an advanced API. If you just want to configure built-in reporters, read the ["Reporters"](/guide/reporters) guide.
-:::
-
-Vitest has its own test run lifecycle. These are represented by reporter's methods:
-
-- [`onInit`](#oninit)
-- [`onTestRunStart`](#ontestrunstart)
-  - [`onTestModuleQueued`](#ontestmodulequeued)
-  - [`onTestModuleCollected`](#ontestmodulecollected)
-  - [`onTestModuleStart`](#ontestmodulestart)
-    - [`onTestSuiteReady`](#ontestsuiteready)
-      - [`onHookStart(beforeAll)`](#onhookstart)
-      - [`onHookEnd(beforeAll)`](#onhookend)
-        - [`onTestCaseReady`](#ontestcaseready)
-          - [`onTestCaseAnnotate`](#ontestcaseannotate) <Version>3.2.0</Version>
-          - [`onTestCaseArtifactRecord`](#ontestcaseartifactrecord) <Version type="experimental">4.0.11</Version>
-          - [`onHookStart(beforeEach)`](#onhookstart)
-          - [`onHookEnd(beforeEach)`](#onhookend)
-          - [`onHookStart(afterEach)`](#onhookstart)
-          - [`onHookEnd(afterEach)`](#onhookend)
-        - [`onTestCaseResult`](#ontestcaseresult)
-      - [`onHookStart(afterAll)`](#onhookstart)
-      - [`onHookEnd(afterAll)`](#onhookend)
-    - [`onTestSuiteResult`](#ontestsuiteresult)
-  - [`onTestModuleEnd`](#ontestmoduleend)
-  - [`onCoverage`](#oncoverage)
-- [`onTestRunEnd`](#ontestrunend)
-
-Tests and suites within a single module will be reported in order unless they were skipped. All skipped tests are reported at the end of suite/module.
-
-Note that since test modules can run in parallel, Vitest will report them in parallel.
-
-This guide lists all supported reporter methods. However, don't forget that instead of creating your own reporter, you can [extend existing one](/guide/advanced/reporters) instead:
-
-```ts [custom-reporter.js]
-import { BaseReporter } from 'vitest/node'
-
-export default class CustomReporter extends BaseReporter {
-  onTestRunEnd(testModules, errors) {
-    console.log(testModule.length, 'tests finished running')
-    super.onTestRunEnd(testModules, errors)
-  }
-}
-```
-
-## onInit
-
-```ts
-function onInit(vitest: Vitest): Awaitable<void>
-```
-
-This method is called when [Vitest](/api/advanced/vitest) was initiated or started, but before the tests were filtered.
-
-::: info
-Internally this method is called inside [`vitest.start`](/api/advanced/vitest#start), [`vitest.standalone`](/api/advanced/vitest#standalone) or [`vitest.mergeReports`](/api/advanced/vitest#mergereports). If you are using programmatic API, make sure to call either one depending on your needs before calling [`vitest.runTestSpecifications`](/api/advanced/vitest#runtestspecifications), for example. Built-in CLI will always run methods in correct order.
-:::
-
-Note that you can also get access to `vitest` instance from test cases, suites and test modules via a [`project`](/api/advanced/test-project) property, but it might also be useful to store a reference to `vitest` in this method.
-
-::: details Example
-```ts
-import type { Reporter, TestSpecification, Vitest } from 'vitest/node'
-
-class MyReporter implements Reporter {
-  private vitest!: Vitest
-
-  onInit(vitest: Vitest) {
-    this.vitest = vitest
-  }
-
-  onTestRunStart(specifications: TestSpecification[]) {
-    console.log(
-      specifications.length,
-      'test files will run in',
-      this.vitest.config.root,
-    )
-  }
-}
-
-export default new MyReporter()
-```
-:::
-
-## onBrowserInit {#onbrowserinit}
-
-```ts
-function onBrowserInit(project: TestProject): Awaitable<void>
-```
-
-This method is called when the browser instance is initiated. It receives an instance of the project for which the browser is initiated. `project.browser` will always be defined when this method is called.
-
-## onTestRunStart
-
-```ts
-function onTestRunStart(
-  specifications: TestSpecification[]
-): Awaitable<void>
-```
-
-This method is called when a new test run has started. It receives an array of [test specifications](/api/advanced/test-specification) scheduled to run. This array is readonly and available only for information purposes.
-
-If Vitest didn't find any test files to run, this event will be invoked with an empty array, and then [`onTestRunEnd`](#ontestrunend) will be called immediately after.
-
-::: details Example
-```ts
-import type { Reporter, TestSpecification } from 'vitest/node'
-
-class MyReporter implements Reporter {
-  onTestRunStart(specifications: TestSpecification[]) {
-    console.log(specifications.length, 'test files will run')
-  }
-}
-
-export default new MyReporter()
-```
-:::
-
-## onTestRunEnd
-
-```ts
-function onTestRunEnd(
-  testModules: ReadonlyArray<TestModule>,
-  unhandledErrors: ReadonlyArray<SerializedError>,
-  reason: TestRunEndReason
-): Awaitable<void>
-```
-
-This method is called after all tests have finished running and the coverage merged all reports, if it's enabled. Note that you can get the coverage information in [`onCoverage`](#oncoverage) hook.
-
-It receives a readonly list of test modules. You can iterate over it via a [`testModule.children`](/api/advanced/test-collection) property to report the state and errors, if any.
-
-The second argument is a readonly list of unhandled errors that Vitest wasn't able to attribute to any test. These can happen outside of the test run because of an error in a plugin, or inside the test run as a side-effect of a non-awaited function (for example, a timeout that threw an error after the test has finished running).
-
-The third argument indicated why the test run was finished:
-
-- `passed`: test run was finished normally and there are no errors
-- `failed`: test run has at least one error (due to a syntax error during collection or an actual error during test execution)
-- `interrupted`: test was interrupted by [`vitest.cancelCurrentRun`](/api/advanced/vitest#cancelcurrentrun) call or `Ctrl+C` was pressed in the terminal (note that it's still possible to have failed tests in this case)
-
-If Vitest didn't find any test files to run, this event will be invoked with empty arrays of modules and errors, and the state will depend on the value of [`config.passWithNoTests`](/config/passwithnotests).
-
-::: details Example
-```ts
-import type {
-  Reporter,
-  SerializedError,
-  TestModule,
-  TestRunEndReason,
-  TestSpecification
-} from 'vitest/node'
-
-class MyReporter implements Reporter {
-  onTestRunEnd(
-    testModules: ReadonlyArray<TestModule>,
-    unhandledErrors: ReadonlyArray<SerializedError>,
-    reason: TestRunEndReason,
-  ) {
-    if (reason === 'passed') {
-      testModules.forEach(module => console.log(module.moduleId, 'succeeded'))
-    }
-    else if (reason === 'failed') {
-      // note that this will skip possible errors in suites
-      // you can get them from testSuite.errors()
-      for (const testCase of testModules.children.allTests()) {
-        if (testCase.result().state === 'failed') {
-          console.log(testCase.fullName, 'in', testCase.module.moduleId, 'failed')
-          console.log(testCase.result().errors)
-        }
-      }
-    }
-    else {
-      console.log('test run was interrupted, skipping report')
-    }
-  }
-}
-
-export default new MyReporter()
-```
-:::
-
-## onCoverage
-
-```ts
-function onCoverage(coverage: unknown): Awaitable<void>
-```
-
-This hook is called after coverage results have been processed. Coverage provider's reporters are called after this hook. The typings of `coverage` depends on the `coverage.provider`. For Vitest's default built-in providers you can import the types from `istanbul-lib-coverage` package:
-
-```ts
-import type { CoverageMap } from 'istanbul-lib-coverage'
-
-declare function onCoverage(coverage: CoverageMap): Awaitable<void>
-```
-
-If Vitest didn't perform any coverage, this hook is not called.
-
-## onTestModuleQueued
-
-```ts
-function onTestModuleQueued(testModule: TestModule): Awaitable<void>
-```
-
-This method is called right before Vitest imports the setup file and the test module itself. This means that `testModule` will have no [`children`](/api/advanced/test-suite#children) yet, but you can start reporting it as the next test to run.
-
-## onTestModuleCollected
-
-```ts
-function onTestModuleCollected(testModule: TestModule): Awaitable<void>
-```
-
-This method is called when all tests inside the file were collected, meaning [`testModule.children`](/api/advanced/test-suite#children) collection is populated, but tests don't have any results yet.
-
-## onTestModuleStart
-
-```ts
-function onTestModuleStart(testModule: TestModule): Awaitable<void>
-```
-
-This method is called right after [`onTestModuleCollected`](#ontestmodulecollected) unless Vitest runs in collection mode ([`vitest.collect()`](/api/advanced/vitest#collect) or `vitest collect` in the CLI), in this case it will not be called at all because there are no tests to run.
-
-## onTestModuleEnd
-
-```ts
-function onTestModuleEnd(testModule: TestModule): Awaitable<void>
-```
-
-This method is called when every test in the module finished running. This means, every test inside [`testModule.children`](/api/advanced/test-suite#children) will have a `test.result()` that is not equal to `pending`.
-
-## onHookStart
-
-```ts
-function onHookStart(context: ReportedHookContext): Awaitable<void>
-```
-
-This method is called when any of these hooks have started running:
-
-- `beforeAll`
-- `afterAll`
-- `beforeEach`
-- `afterEach`
-
-If `beforeAll` or `afterAll` are started, the `entity` will be either [`TestSuite`](/api/advanced/test-suite) or [`TestModule`](/api/advanced/test-module).
-
-If `beforeEach` or `afterEach` are started, the `entity` will always be [`TestCase`](/api/advanced/test-case).
-
-::: warning
-`onHookStart` method will not be called if the hook did not run during the test run.
-:::
-
-## onHookEnd
-
-```ts
-function onHookEnd(context: ReportedHookContext): Awaitable<void>
-```
-
-This method is called when any of these hooks have finished running:
-
-- `beforeAll`
-- `afterAll`
-- `beforeEach`
-- `afterEach`
-
-If `beforeAll` or `afterAll` have finished, the `entity` will be either [`TestSuite`](/api/advanced/test-suite) or [`TestModule`](/api/advanced/test-module).
-
-If `beforeEach` or `afterEach` have finished, the `entity` will always be [`TestCase`](/api/advanced/test-case).
-
-::: warning
-`onHookEnd` method will not be called if the hook did not run during the test run.
-:::
-
-## onTestSuiteReady
-
-```ts
-function onTestSuiteReady(testSuite: TestSuite): Awaitable<void>
-```
-
-This method is called before the suite starts to run its tests. This method is also called if the suite was skipped.
-
-If the file doesn't have any suites, this method will not be called. Consider using `onTestModuleStart` to cover this use case.
-
-## onTestSuiteResult
-
-```ts
-function onTestSuiteResult(testSuite: TestSuite): Awaitable<void>
-```
-
-This method is called after the suite has finished running tests. This method is also called if the suite was skipped.
-
-If the file doesn't have any suites, this method will not be called. Consider using `onTestModuleEnd` to cover this use case.
-
-## onTestCaseReady
-
-```ts
-function onTestCaseReady(testCase: TestCase): Awaitable<void>
-```
-
-This method is called before the test starts to run or it was skipped. Note that `beforeEach` and `afterEach` hooks are considered part of the test because they can influence the result.
-
-::: warning
-Notice that it's possible to have [`testCase.result()`](/api/advanced/test-case#result) with `passed` or `failed` state already when `onTestCaseReady` is called. This can happen if test was running too fast and both `onTestCaseReady` and `onTestCaseResult` were scheduled to run in the same microtask.
-:::
-
-## onTestCaseResult
-
-```ts
-function onTestCaseResult(testCase: TestCase): Awaitable<void>
-```
-
-This method is called when the test has finished running or was just skipped. Note that this will be called after the `afterEach` hook is finished, if there are any.
-
-At this point, [`testCase.result()`](/api/advanced/test-case#result) will have non-pending state.
-
-## onTestCaseAnnotate <Version>3.2.0</Version> {#ontestcaseannotate}
-
-```ts
-function onTestCaseAnnotate(
-  testCase: TestCase,
-  annotation: TestAnnotation,
-): Awaitable<void>
-```
-
-The `onTestCaseAnnotate` hook is associated with the [`context.annotate`](/guide/test-context#annotate) method. When `annotate` is invoked, Vitest serialises it and sends the same attachment to the main thread where reporter can interact with it.
-
-If the path is specified, Vitest stores it in a separate directory (configured by [`attachmentsDir`](/config/attachmentsdir)) and modifies the `path` property to reference it.
-
-## onTestCaseArtifactRecord <Version type="experimental">4.0.11</Version> {#ontestcaseartifactrecord}
-
-```ts
-function onTestCaseArtifactRecord(
-  testCase: TestCase,
-  artifact: TestArtifact,
-): Awaitable<void>
-```
-
-The `onTestCaseArtifactRecord` hook is associated with the [`recordArtifact`](/api/advanced/artifacts#recordartifact) utility. When `recordArtifact` is invoked, Vitest serialises it and sends the same attachment to the main thread where reporter can interact with it.
-
-If the path is specified, Vitest stores it in a separate directory (configured by [`attachmentsDir`](/config/attachmentsdir)) and modifies the `path` property to reference it.
-
-Note: annotations, [even though they're built on top of this feature](/api/advanced/artifacts#relationship-with-annotations), won't hit this hook and won't appear in the `task.artifacts` array for backwards compatibility reasons until the next major version.

package/public/vendor/vitest-docs/api/advanced/runner.md

@@ -1,334 +0,0 @@
-# Runner API <Badge type="danger">advanced</Badge>
-
-::: warning
-This is advanced API. If you just want to [run tests](/guide/), you probably don't need this. It is primarily used by library authors.
-:::
-
-You can specify a path to your test runner with the `runner` option in your configuration file. This file should have a default export with a class constructor implementing these methods:
-
-```ts
-export interface VitestRunner {
-  /**
-   * First thing that's getting called before actually collecting and running tests.
-   */
-  onBeforeCollect?: (paths: string[]) => unknown
-  /**
-   * Called after collecting tests and before "onBeforeRun".
-   */
-  onCollected?: (files: File[]) => unknown
-
-  /**
-   * Called when test runner should cancel next test runs.
-   * Runner should listen for this method and mark tests and suites as skipped in
-   * "onBeforeRunSuite" and "onBeforeRunTask" when called.
-   */
-  onCancel?: (reason: CancelReason) => unknown
-
-  /**
-   * Called before running a single test. Doesn't have "result" yet.
-   */
-  onBeforeRunTask?: (test: Test) => unknown
-  /**
-   * Called before actually running the test function. Already has "result" with "state" and "startTime".
-   */
-  onBeforeTryTask?: (test: Test, options: { retry: number; repeats: number }) => unknown
-  /**
-   * Called after result and state are set.
-   */
-  onAfterRunTask?: (test: Test) => unknown
-  /**
-   * Called right after running the test function. Doesn't have new state yet. Will not be called, if the test function throws.
-   */
-  onAfterTryTask?: (test: Test, options: { retry: number; repeats: number }) => unknown
-  /**
-   * Called after the retry resolution happened. Unlike `onAfterTryTask`, the test now has a new state.
-   * All `after` hooks were also called by this point.
-   */
-  onAfterRetryTask?: (test: Test, options: { retry: number; repeats: number }) => unknown
-
-  /**
-   * Called before running a single suite. Doesn't have "result" yet.
-   */
-  onBeforeRunSuite?: (suite: Suite) => unknown
-  /**
-   * Called after running a single suite. Has state and result.
-   */
-  onAfterRunSuite?: (suite: Suite) => unknown
-
-  /**
-   * If defined, will be called instead of usual Vitest suite partition and handling.
-   * "before" and "after" hooks will not be ignored.
-   */
-  runSuite?: (suite: Suite) => Promise<void>
-  /**
-   * If defined, will be called instead of usual Vitest handling. Useful, if you have your custom test function.
-   * "before" and "after" hooks will not be ignored.
-   */
-  runTask?: (test: TaskPopulated) => Promise<void>
-
-  /**
-   * Called, when a task is updated. The same as "onTaskUpdate" in a reporter, but this is running in the same thread as tests.
-   */
-  onTaskUpdate?: (task: [string, TaskResult | undefined, TaskMeta | undefined][]) => Promise<void>
-
-  /**
-   * Called before running all tests in collected paths.
-   */
-  onBeforeRunFiles?: (files: File[]) => unknown
-  /**
-   * Called right after running all tests in collected paths.
-   */
-  onAfterRunFiles?: (files: File[]) => unknown
-  /**
-   * 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 with a runner, consider using "beforeAll" in "setupFiles" instead.
-   */
-  extendTaskContext?: (context: TestContext) => TestContext
-  /**
-   * Called when certain files are imported. Can be called in two situations: to collect tests and to import setup files.
-   */
-  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown
-  /**
-   * Function that is called when the runner attempts to get the value when `test.extend` is used with `{ injected: true }`
-   */
-  injectValue?: (key: string) => unknown
-  /**
-   * Publicly available configuration.
-   */
-  config: VitestRunnerConfig
-  /**
-   * The name of the current pool. Can affect how stack trace is inferred on the server side.
-   */
-  pool?: string
-}
-```
-
-When initiating this class, Vitest passes down Vitest config, - you should expose it as a `config` property:
-
-```ts [runner.ts]
-import type { RunnerTestFile, SerializedConfig, TestRunner, VitestTestRunner } from 'vitest'
-
-class CustomRunner extends TestRunner implements VitestTestRunner {
-  public config: SerializedConfig
-
-  constructor(config: SerializedConfig) {
-    this.config = config
-  }
-
-  onAfterRunFiles(files: RunnerTestFile[]) {
-    console.log('finished running', files)
-  }
-}
-
-export default CustomRunner
-```
-
-::: warning
-Vitest also injects an instance of `ModuleRunner` from `vite/module-runner` as `moduleRunner` property. You can use it to process files in `importFile` method (this is default behavior of `TestRunner` and `BenchmarkRunner`).
-
-`ModuleRunner` exposes `import` method, which is used to import test files in a Vite-friendly environment. Meaning, it will resolve imports and transform file content at runtime so that Node can understand it:
-
-```ts
-export default class Runner {
-  async importFile(filepath: string) {
-    await this.moduleRunner.import(filepath)
-  }
-}
-```
-:::
-
-::: warning
-If you don't have a custom runner or didn't define `runTest` method, Vitest will try to retrieve a task automatically. If you didn't add a function with `setFn`, it will fail.
-:::
-
-::: tip
-Snapshot support and some other features depend on the runner. If you don't want to lose it, you can extend your runner from `VitestTestRunner` imported from `vitest/runners`. It also exposes `NodeBenchmarkRunner`, if you want to extend benchmark functionality.
-:::
-
-## Tasks
-
-::: warning
-The "Runner Tasks API" is experimental and should primarily be used only in the test runtime. Vitest also exposes the ["Reported Tasks API"](/api/advanced/test-module), which should be preferred when working in the main thread (inside the reporter, for example).
-
-The team is currently discussing if "Runner Tasks" should be replaced by "Reported Tasks" in the future.
-:::
-
-Suites and tests are called `tasks` internally. Vitest runner initiates a `File` task before collecting any tests - this is a superset of `Suite` with a few additional properties. It is available on every task (including `File`) as a `file` property.
-
-```ts
-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 test 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
-}
-```
-
-Every suite has a `tasks` property that is populated during collection phase. It is useful to traverse the task tree from the top down.
-
-```ts
-interface Suite extends TaskBase {
-  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[]
-}
-```
-
-Every task has a `suite` property that references a suite it is located in. If `test` or `describe` are initiated at the top level, they will not have a `suite` property (it will **not** be equal to `file`!). `File` also never has a `suite` property. It is useful to traverse the tasks from the bottom up.
-
-```ts
-interface Test<ExtraContext = object> extends TaskBase {
-  type: 'test'
-  /**
-   * Test context that will be passed to the test function.
-   */
-  context: TestContext & ExtraContext
-  /**
-   * File task. It's the root task of the file.
-   */
-  file: File
-  /**
-   * Whether the task was skipped by calling `context.skip()`.
-   */
-  pending?: boolean
-  /**
-   * Whether the task should succeed if it fails. If the task fails, it will be marked as passed.
-   */
-  fails?: boolean
-  /**
-   * Store promises (from async expects) to wait for them before finishing the test
-   */
-  promises?: Promise<any>[]
-}
-```
-
-Every task can have a `result` field. Suites can only have this field if an error thrown within a suite callback or `beforeAll`/`afterAll` callbacks prevents them from collecting tests. Tests always have this field after their callbacks are called - the `state` and `errors` fields are present depending on the outcome. If an error was thrown in `beforeEach` or `afterEach` callbacks, the thrown error will be present in `task.result.errors`.
-
-```ts
-export 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?: TestError[]
-  /**
-   * 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
-  /**
-   * State of related to this task hooks. Useful during reporting.
-   */
-  hooks?: Partial<Record<'afterAll' | 'beforeAll' | 'beforeEach' | 'afterEach', 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
-}
-```
-
-## Your Task Function
-
-Vitest exposes `createTaskCollector` utility to create your own `test` method. It behaves the same way as a test, but calls a custom method during collection.
-
-A task is an object that is part of a suite. It is automatically added to the current suite with a `suite.task` method:
-
-```js [custom.js]
-export { afterAll, beforeAll, describe, TestRunner } from 'vitest'
-
-// this function will be called during collection phase:
-// don't call function handler here, add it to suite tasks
-// with "getCurrentSuite().task()" method
-// note: createTaskCollector provides support for "todo"/"each"/...
-export const myCustomTask = TestRunner.createTaskCollector(
-  function (name, fn, timeout) {
-    TestRunner.getCurrentSuite().task(name, {
-      ...this, // so "todo"/"skip"/... is tracked correctly
-      meta: {
-        customPropertyToDifferentiateTask: true
-      },
-      handler: fn,
-      timeout,
-    })
-  }
-)
-```
-
-```js [tasks.test.js]
-import {
-  afterAll,
-  beforeAll,
-  describe,
-  myCustomTask
-} from './custom.js'
-import { gardener } from './gardener.js'
-
-describe('take care of the garden', () => {
-  beforeAll(() => {
-    gardener.putWorkingClothes()
-  })
-
-  myCustomTask('weed the grass', () => {
-    gardener.weedTheGrass()
-  })
-  myCustomTask.todo('mow the lawn', () => {
-    gardener.mowerTheLawn()
-  })
-  myCustomTask('water flowers', () => {
-    gardener.waterFlowers()
-  })
-
-  afterAll(() => {
-    gardener.goHome()
-  })
-})
-```
-
-```bash
-vitest ./garden/tasks.test.js
-```