@vitest-agent/mcp 1.0.0 → 1.0.1

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

@@ -0,0 +1,189 @@
+# Test Artifacts <Advanced /> <Version type="experimental">4.0.11</Version> <Experimental />
+
+::: warning
+This is an advanced API. As a user, you most likely want to use [test annotations](/guide/test-annotations) to add notes or context to your tests instead. This is primarily used internally and by library authors.
+:::
+
+Test artifacts allow attaching or recording structured data, files, or metadata during test execution. This is a low-level feature primarily designed for:
+
+- Internal use ([`annotate`](/guide/test-annotations) is built on top of the artifact system)
+- Framework authors creating custom testing tools on top of Vitest
+
+Each artifact includes:
+
+- A type discriminator which is a unique identifier for the artifact type
+- Custom data, can be any relevant information
+- Optional attachments, either files or inline content associated with the artifact
+- A source code location indicating where the artifact was created
+
+Vitest automatically manages attachment serialization (files are copied to [`attachmentsDir`](/config/attachmentsdir)) and injects source location metadata, so you can focus on the data you want to record. All artifacts **must** extend from [`TestArtifactBase`](#testartifactbase) and all attachments from [`TestAttachment`](#testattachment) to be correctly handled internally.
+
+## API
+
+### `recordArtifact` <Experimental /> {#recordartifact}
+
+::: warning
+`recordArtifact` is an experimental API. Breaking changes might not follow SemVer, please pin Vitest's version when using it.
+
+The API surface may change based on feedback. We encourage you to try it out and share your experience with the team.
+:::
+
+```ts
+function recordArtifact<Artifact extends TestArtifact>(task: Test, artifact: Artifact): Promise<Artifact>
+```
+
+The `recordArtifact` function records an artifact during test execution and returns it. It expects a [task](/api/advanced/runner#tasks) as the first parameter and an object assignable to [`TestArtifact`](#testartifact) as the second.
+
+::: info
+Artifacts must be recorded before the task is reported. Any artifacts recorded after that will not be included in the task.
+:::
+
+When an artifact is recorded on a test, it emits an `onTestArtifactRecord` runner event and a [`onTestCaseArtifactRecord` reporter event](/api/advanced/reporters#ontestcaseartifactrecord). To retrieve recorded artifacts from a test case, use the [`artifacts()`](/api/advanced/test-case#artifacts) method.
+
+Note: annotations, [even though they're built on top of this feature](#relationship-with-annotations), won't appear in the `task.artifacts` array for backwards compatibility reasons until the next major version.
+
+### `TestArtifact`
+
+The `TestArtifact` type is a union containing all artifacts Vitest can produce, including custom ones. All artifacts extend from [`TestArtifactBase`](#testartifactbase)
+
+### `TestArtifactBase` <Experimental /> {#testartifactbase}
+
+```ts
+export interface TestArtifactBase {
+  /** File or data attachments associated with this artifact */
+  attachments?: TestAttachment[]
+  /** Source location where this artifact was created */
+  location?: TestArtifactLocation
+}
+```
+
+The `TestArtifactBase` interface is the base for all test artifacts.
+
+Extend this interface when creating custom test artifacts. Vitest automatically manages the `attachments` array and injects the `location` property to indicate where the artifact was created in your test code.
+
+::: danger
+When running with [`api.allowWrite`](/config/api#api-allowwrite) or [`browser.api.allowWrite`](/config/browser/api#api-allowwrite) disabled, Vitest empties the `attachments` array on every artifact before reporting it.
+
+If your custom artifact narrows the `attachments` type (e.g. to a tuple), include `| []` in the union so the type reflects what actually happens at runtime.
+:::
+
+### `TestAttachment`
+
+```ts
+export interface TestAttachment {
+  /** MIME type of the attachment (e.g., 'image/png', 'text/plain') */
+  contentType?: string
+  /** File system path to the attachment */
+  path?: string
+  /** Inline attachment content as a string or raw binary data */
+  body?: string | Uint8Array
+  /**
+   * @experimental
+   * How the string `body` is encoded.
+   * - `'base64'` (default): body is already base64-encoded
+   * - `'utf-8'`: body is a utf8 string
+   */
+  bodyEncoding?: 'base64' | 'utf-8'
+}
+```
+
+The `TestAttachment` interface represents a file or data attachment associated with a test artifact.
+
+Attachments can be either file-based (via `path`) or inline content (via `body`). The `contentType` helps consumers understand how to interpret the attachment data.
+
+If you pass a string `body`, Vitest assumes it is already base64-encoded unless you set `bodyEncoding: 'utf-8'`. When you pass `body` as a `Uint8Array`, Vitest automatically encodes it as base64. The `bodyEncoding` option only applies to inline `body` attachments, not `path` attachments.
+
+### `TestArtifactLocation`
+
+```ts
+export interface TestArtifactLocation {
+  /** Line number in the source file (1-indexed) */
+  line: number
+  /** Column number in the line (1-indexed) */
+  column: number
+  /** Path to the source file */
+  file: string
+}
+```
+
+The `TestArtifactLocation` interface represents the source code location information for a test artifact. It indicates where in the source code the artifact originated from.
+
+### `TestArtifactRegistry`
+
+The `TestArtifactRegistry` interface is a registry for custom test artifact types.
+
+Augmenting this interface using [TypeScript's module augmentation feature](https://typescriptlang.org/docs/handbook/declaration-merging#module-augmentation) allows registering custom artifact types that tests can produce.
+
+Each custom artifact should extend [`TestArtifactBase`](#testartifactbase) and include a unique `type` discriminator property.
+
+Here are a few guidelines or best practices to follow:
+
+- Try using a `Symbol` as the **registry key** to guarantee uniqueness
+- The `type` property should follow the pattern `'package-name:artifact-name'`, **`'internal:'` is a reserved prefix**
+- Use `attachments` to include files or data; extend [`TestAttachment`](#testattachment) for custom metadata
+- If you narrow the `attachments` type (e.g. to a tuple), include `| []` in the union since Vitest may empty the array at runtime (see [`TestArtifactBase`](#testartifactbase))
+- `location` property is automatically injected
+
+## Custom Artifacts
+
+To use and manage artifacts in a type-safe manner, you need to create its type and register it:
+
+```ts
+import type { TestArtifactBase, TestAttachment } from 'vitest'
+
+interface A11yReportAttachment extends TestAttachment {
+  contentType: 'text/html'
+  path: string
+}
+
+interface AccessibilityArtifact extends TestArtifactBase {
+  type: 'a11y:report'
+  passed: boolean
+  wcagLevel: 'A' | 'AA' | 'AAA'
+  attachments: [A11yReportAttachment] | []
+}
+
+const a11yReportKey = Symbol('report')
+
+declare module 'vitest' {
+  interface TestArtifactRegistry {
+    [a11yReportKey]: AccessibilityArtifact
+  }
+}
+```
+
+As long as the types are assignable to their bases and don't have errors, everything should work fine and you should be able to record artifacts using [`recordArtifact`](#recordartifact):
+
+```ts
+async function toBeAccessible(
+  this: MatcherState,
+  actual: Element,
+  wcagLevel: 'A' | 'AA' | 'AAA' = 'AA'
+): AsyncExpectationResult {
+  const report = await runAccessibilityAudit(actual, wcagLevel)
+
+  await recordArtifact(this.task, {
+    type: 'a11y:report',
+    passed: report.violations.length === 0,
+    wcagLevel,
+    attachments: [{
+      contentType: 'text/html',
+      path: report.path,
+    }],
+  })
+
+  return {
+    pass: violations.length === 0,
+    message: () => `Found ${report.violations.length} accessibility violation(s)`
+  }
+}
+```
+
+## Relationship with Annotations
+
+Test annotations are built on top of the artifact system. When using annotations in tests, they create `internal:annotation` artifacts under the hood. However, annotations are:
+
+- Simpler to use
+- Designed for end-users, not developers
+
+Use annotations if you just want to add notes to your tests. Use artifacts if you need custom data.

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

@@ -0,0 +1,68 @@
+# 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/public/vendor/vitest-docs/api/advanced/plugin.md

@@ -0,0 +1,168 @@
+# 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.