@vitest-agent/mcp 1.1.0 → 1.3.0

package/vendor/vitest-docs/api/advanced/metadata.md

@@ -1,68 +0,0 @@
-# Task Metadata <Badge type="danger">advanced</Badge>
-
-If you are developing a custom reporter or using Vitest Node.js API, you might find it useful to pass data from tests that are being executed in various contexts to your reporter or custom Vitest handler.
-
-To accomplish this, relying on the [test context](/guide/test-context) is not feasible since it cannot be serialized. However, with Vitest, you can utilize the `meta` property available on every task (suite or test) to share data between your tests and the Node.js process. It's important to note that this communication is one-way only, as the `meta` property can only be modified from within the test context. Any changes made within the Node.js context will not be visible in your tests.
-
-You can populate `meta` property on test context or inside `beforeAll`/`afterAll` hooks for suite tasks.
-
-```ts
-afterAll((suite) => {
-  suite.meta.done = true
-})
-
-test('custom', ({ task }) => {
-  task.meta.custom = 'some-custom-handler'
-})
-```
-
-Once a test is completed, Vitest will send a task including the result and `meta` to the Node.js process using RPC, and then report it in `onTestCaseResult` and other hooks that have access to tasks. To process this test case, you can utilize the `onTestCaseResult` method available in your reporter implementation:
-
-```ts [custom-reporter.js]
-import type { Reporter, TestCase, TestModule } from 'vitest/node'
-
-export default {
-  onTestCaseResult(testCase: TestCase) {
-    // custom === 'some-custom-handler' ✅
-    const { custom } = testCase.meta()
-  },
-  onTestRunEnd(testModule: TestModule) {
-    testModule.meta().done === true
-    testModule.children.at(0).meta().custom === 'some-custom-handler'
-  }
-} satisfies Reporter
-```
-
-::: danger BEWARE
-Vitest uses different methods to communicate with the Node.js process.
-
-- If Vitest runs tests inside worker threads, it will send data via [message port](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort)
-- If Vitest uses child process, the data will be send as a serialized Buffer via [`process.send`](https://nodejs.org/api/process.html#processsendmessage-sendhandle-options-callback) API
-- If Vitest runs tests in the browser, the data will be stringified using [flatted](https://npmx.dev/package/flatted) package
-
-This property is also present on every test in the `json` reporter, so make sure that data can be serialized into JSON.
-
-Also, make sure you serialize [Error properties](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#error_types) before you set them.
-:::
-
-You can also get this information from Vitest state when tests finished running:
-
-```ts
-const vitest = await createVitest('test')
-const { testModules } = await vitest.start()
-
-const testModule = testModules[0]
-testModule.meta().done === true
-testModule.children.at(0).meta().custom === 'some-custom-handler'
-```
-
-It's also possible to extend type definitions when using TypeScript:
-
-```ts
-declare module 'vitest' {
-  interface TaskMeta {
-    done?: boolean
-    custom?: string
-  }
-}
-```

package/vendor/vitest-docs/api/advanced/plugin.md

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

package/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.