@vitest-agent/mcp 1.1.0 → 1.2.0

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

package/vendor/vitest-docs/api/advanced/test-case.md

@@ -1,302 +0,0 @@
-# TestCase
-
-The `TestCase` class represents a single test. This class is only available in the main thread. Refer to the ["Runner API"](/api/advanced/runner#tasks) if you are working with runtime tasks.
-
-The `TestCase` instance always has a `type` property with the value of `test`. You can use it to distinguish between different task types:
-
-```ts
-if (task.type === 'test') {
-  task // TestCase
-}
-```
-
-## project
-
-This references the [`TestProject`](/api/advanced/test-project) that the test belongs to.
-
-## module
-
-This is a direct reference to the [`TestModule`](/api/advanced/test-module) where the test is defined.
-
-## name
-
-This is a test name that was passed to the `test` function.
-
-```ts
-import { test } from 'vitest'
-
-// [!code word:'the validation works correctly']
-test('the validation works correctly', () => {
-  // ...
-})
-```
-
-## fullName
-
-The name of the test including all parent suites separated with `>` symbol. This test has a full name "the validation logic > the validation works correctly":
-
-```ts
-import { describe, test } from 'vitest'
-
-// [!code word:'the validation works correctly']
-// [!code word:'the validation logic']
-describe('the validation logic', () => {
-  test('the validation works correctly', () => {
-    // ...
-  })
-})
-```
-
-## id
-
-This is test's 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](/api/advanced/test-project) name, module ID and test order.
-
-The ID looks like this:
-
-```
-1223128da3_0_0
-^^^^^^^^^^ the file hash
-           ^ suite index
-             ^ test index
-```
-
-::: tip
-You can generate file hash with `generateFileHash` function from `vitest/node` which is available since Vitest 3:
-
-```ts
-import { generateFileHash } from 'vitest/node'
-
-const hash = generateFileHash(
-  '/file/path.js', // relative path
-  undefined, // the project name or `undefined` is not set
-)
-```
-:::
-
-::: danger
-Don't try to parse the ID. It can have a minus at the start: `-1223128da3_0_0_0`.
-:::
-
-## location
-
-The location in the module where the test was defined. Locations are collected only if [`includeTaskLocation`](/config/includetasklocation) is enabled in the config. Note that this option is automatically enabled if `--reporter=html`, `--ui` or `--browser` flags are used.
-
-The location of this test will be equal to `{ line: 3, column: 1 }`:
-
-```ts:line-numbers {3}
-import { test } from 'vitest'
-
-test('the validation works correctly', () => {
-  // ...
-})
-```
-
-## parent
-
-Parent [suite](/api/advanced/test-suite). If the test was called directly inside the [module](/api/advanced/test-module), the parent will be the module itself.
-
-## options
-
-```ts
-interface TaskOptions {
-  readonly each: boolean | undefined
-  readonly fails: boolean | undefined
-  readonly concurrent: boolean | undefined
-  readonly shuffle: boolean | undefined
-  readonly retry: number | undefined
-  readonly repeats: number | undefined
-  readonly tags: string[] | undefined
-  readonly timeout: number | undefined
-  readonly mode: 'run' | 'only' | 'skip' | 'todo'
-}
-```
-
-The options that test was collected with.
-
-## tags <Version>4.1.0</Version> {#tags}
-
-[Tags](/guide/test-tags) that were implicitly or explicitly assigned to the test.
-
-## ok
-
-```ts
-function ok(): boolean
-```
-
-Checks if the test did not fail the suite. If the test is not finished yet or was skipped, it will return `true`.
-
-## meta
-
-```ts
-function meta(): TaskMeta
-```
-
-Custom [metadata](/api/advanced/metadata) that was attached to the test during its execution. The meta can be attached by assigning a property to the `ctx.task.meta` object during a test run:
-
-```ts {3,6}
-import { test } from 'vitest'
-
-test('the validation works correctly', ({ task }) => {
-  // ...
-
-  task.meta.decorated = false
-})
-```
-
-If the test did not finish running yet, the meta will be an empty object, unless it has static meta:
-
-```ts
-test('the validation works correctly', { meta: { decorated: true } })
-```
-
-Since Vitest 4.1, Vitest inherits [`meta`](/api/advanced/test-suite#meta) property defined on the [suite](/api/advanced/test-suite).
-
-## result
-
-```ts
-function result(): TestResult
-```
-
-Test results. If test is not finished yet or was just collected, it will be equal to `TestResultPending`:
-
-```ts
-export interface TestResultPending {
-  /**
-   * The test was collected, but didn't finish running yet.
-   */
-  readonly state: 'pending'
-  /**
-   * Pending tests have no errors.
-   */
-  readonly errors: undefined
-}
-```
-
-If the test was skipped, the return value will be `TestResultSkipped`:
-
-```ts
-interface TestResultSkipped {
-  /**
-   * The test was skipped with `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
-}
-```
-
-::: tip
-If the test was skipped because another test has `only` flag, the `options.mode` will be equal to `skip`.
-:::
-
-If the test failed, the return value will be `TestResultFailed`:
-
-```ts
-interface TestResultFailed {
-  /**
-   * The test failed to execute.
-   */
-  readonly state: 'failed'
-  /**
-   * Errors that were thrown during the test execution.
-   */
-  readonly errors: ReadonlyArray<TestError>
-}
-```
-
-If the test passed, the return value will be `TestResultPassed`:
-
-```ts
-interface TestResultPassed {
-  /**
-   * The test passed successfully.
-   */
-  readonly state: 'passed'
-  /**
-   * Errors that were thrown during the test execution.
-   */
-  readonly errors: ReadonlyArray<TestError> | undefined
-}
-```
-
-::: warning
-Note that the test with `passed` state can still have errors attached - this can happen if `retry` was triggered at least once.
-:::
-
-## diagnostic
-
-```ts
-function diagnostic(): TestDiagnostic | undefined
-```
-
-Useful information about the test like duration, memory usage, etc:
-
-```ts
-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
-}
-```
-
-::: info
-`diagnostic()` will return `undefined` if the test was not scheduled to run yet.
-:::
-
-## annotations
-
-```ts
-function annotations(): ReadonlyArray<TestAnnotation>
-```
-
-[Test annotations](/guide/test-annotations) added via the [`task.annotate`](/guide/test-context#annotate) API during the test execution.
-
-## artifacts <Version type="experimental">4.0.11</Version> <Experimental /> {#artifacts}
-
-```ts
-function artifacts(): ReadonlyArray<TestArtifact>
-```
-
-[Test artifacts](/api/advanced/artifacts) recorded via the `recordArtifact` API during the test execution.
-
-## toTestSpecification <Version>4.1.0</Version> {#totestspecification}
-
-```ts
-function toTestSpecification(): TestSpecification
-```
-
-Returns a new [test specification](/api/advanced/test-specification) that can be used to filter or run this specific test case.