@vitest-agent/mcp 1.1.0 → 1.3.0

package/patterns/testing-effect-services-with-mock-layers.md

@@ -1,63 +0,0 @@
-# Testing Effect Services with Mock Layers
-
-## When to use
-
-Reach for this pattern when an Effect service has external dependencies (filesystem, SQLite, network) that you do not want to exercise in unit tests. The codebase under `packages/sdk/src/services/` and `packages/sdk/src/layers/` follows this exact shape.
-
-## The shape
-
-Every Effect service has three pieces:
-
-1. **The service tag** (`Context.Tag`) and interface — under `services/`.
-2. **The live layer** — wires real I/O against `@effect/platform` adapters.
-3. **The test layer** — usually a mutable state container that records what the service was asked to do, with read methods you assert against.
-
-You compose the live layer in production wiring (`ReporterLive`, `CliLive`, `McpLive`); you compose the test layer in tests.
-
-## Minimal example
-
-```typescript
-import { Effect, Layer, Ref } from "effect";
-import { describe, expect, it } from "vitest";
-import { DataStore } from "@vitest-agent/sdk";
-
-// Test layer: accumulates writes into a Ref so tests can read them back.
-const DataStoreTest = Layer.effect(
- DataStore,
- Effect.gen(function* () {
-  const writes = yield* Ref.make<{ runs: ReadonlyArray<unknown> }>({ runs: [] });
-  return DataStore.of({
-   writeRun: (input) =>
-    Ref.update(writes, (s) => ({ runs: [...s.runs, input] })).pipe(
-     Effect.as(1),
-    ),
-   // ... other methods stubbed similarly
-  });
- }),
-);
-
-it("records the run", async () => {
- const program = Effect.gen(function* () {
-  const store = yield* DataStore;
-  yield* store.writeRun({ project: "x" });
-  // assert via your accumulator pattern
- });
- await Effect.runPromise(program.pipe(Effect.provide(DataStoreTest)));
-});
-```
-
-## Why not mock the FileSystem directly?
-
-Layer-level swapping is the testable seam Effect was designed around. Mocking `@effect/platform`'s FileSystem implementation works but loses the type checking that ensures your test layer matches the live interface. Layer.effect with the same Tag forces you to satisfy every method.
-
-## Anti-patterns
-
-- **Don't `Effect.runPromise` inside service implementations** — providing `DataStoreTest` and then having the service call `Effect.runPromise` internally bypasses the layer.
-- **Don't share `Ref`s across tests** — construct the test layer per-test (or use `beforeEach`) so accumulated state doesn't bleed.
-- **Don't assert on layer construction order** — Effect normalizes the merge graph.
-
-## See also
-
-- `vitest://docs/guide/mocking` — Vitest mocking guide (general background)
-- `vitest-agent://patterns/testing-effect-schema-definitions` — Companion pattern; most service inputs are Schema-typed
-- `packages/sdk/src/layers/DataStoreTest.ts` — The canonical example in this codebase

package/resources/index.js

@@ -1,166 +0,0 @@
-import { renderPatternsIndex, renderUpstreamIndex } from "./indexes.js";
-import { decodePatternsManifest, decodeUpstreamManifest } from "./manifest-schema.js";
-import { readPattern } from "./patterns.js";
-import { readUpstreamDoc } from "./upstream-docs.js";
-import { Effect } from "effect";
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-//#region src/resources/index.ts
-/**
-* Convert the readonly ResourceAnnotations decoded from a manifest into
-* the mutable shape the MCP SDK's Annotations type expects. The shape is
-* structurally identical; only the readonly-ness differs.
-*/
-function toSdkAnnotations(a) {
-	const out = {};
-	if (a.audience !== void 0) out.audience = [...a.audience];
-	if (a.priority !== void 0) out.priority = a.priority;
-	return out;
-}
-/**
-* Locate the `public/` directory that holds the served corpus across the
-* source and built layouts. `@savvy-web/bundler` mirrors the package-root
-* `public/` tree next to the emitted chunk (`<pkg>/public/`), so:
-*
-*   built (bundle):  index.js at dist/<env>/pkg/resources/ -> ../public
-*   source (vitest): index.ts at packages/mcp/src/resources/ -> ../../public
-*
-* Probe both and fail loudly when neither carries the patterns index, so a
-* broken build surfaces a clear path list at startup instead of an opaque
-* ENOENT the first time a consumer reads `vitest-agent://patterns/`.
-*/
-function resolveContentRoots() {
-	const here = dirname(fileURLToPath(import.meta.url));
-	const candidates = [join(here, "..", "public"), join(here, "..", "..", "public")];
-	for (const base of candidates) if (existsSync(join(base, "patterns", "_meta.json"))) return {
-		vendorRoot: join(base, "vendor", "vitest-docs"),
-		patternsRoot: join(base, "patterns")
-	};
-	throw new Error(`[vitest-agent-mcp] cannot locate the served corpus: no public/patterns/_meta.json found (tried: ${candidates.join(", ")})`);
-}
-async function listManifestPages(vendorRoot) {
-	const manifestPath = join(vendorRoot, "manifest.json");
-	if (!existsSync(manifestPath)) return [];
-	let raw;
-	try {
-		raw = await readFile(manifestPath, "utf8");
-	} catch {
-		return [];
-	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return [];
-	}
-	const decoded = await Effect.runPromise(decodeUpstreamManifest(parsed).pipe(Effect.catchAll(() => Effect.succeed(null))));
-	if (!decoded?.pages) return [];
-	return decoded.pages.map((page) => ({
-		relativePath: page.path,
-		title: page.title,
-		description: page.description,
-		...page.annotations ? { annotations: page.annotations } : {}
-	}));
-}
-async function listPatternEntries(patternsRoot) {
-	const metaPath = join(patternsRoot, "_meta.json");
-	if (!existsSync(metaPath)) return [];
-	let raw;
-	try {
-		raw = await readFile(metaPath, "utf8");
-	} catch {
-		return [];
-	}
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return [];
-	}
-	const decoded = await Effect.runPromise(decodePatternsManifest(parsed).pipe(Effect.catchAll(() => Effect.succeed(null))));
-	if (!decoded) return [];
-	return decoded.patterns.map((p) => ({
-		slug: p.slug,
-		title: p.title,
-		summary: p.summary,
-		...p.annotations ? { annotations: p.annotations } : {}
-	}));
-}
-function registerAllResources(server) {
-	const { vendorRoot, patternsRoot } = resolveContentRoots();
-	server.registerResource("vitest_docs_index", "vitest://docs/", {
-		title: "Vitest documentation: index",
-		description: "Use first when you need any Vitest API, configuration, or behavioral information and aren't sure which page covers it — lists every page in the vendored snapshot grouped by section (api, config, guide) so you can pick the right `vitest://docs/<path>` URI before fetching.",
-		mimeType: "text/markdown"
-	}, async (uri) => {
-		const result = await renderUpstreamIndex(vendorRoot);
-		return { contents: [{
-			uri: uri.href,
-			mimeType: result.mimeType,
-			text: result.content
-		}] };
-	});
-	server.registerResource("vitest_docs_page", new ResourceTemplate("vitest://docs/{+path}", { list: async () => {
-		return { resources: (await listManifestPages(vendorRoot)).map((page) => ({
-			name: `vitest_docs_${page.relativePath.replace(/\//g, "_")}`,
-			uri: `vitest://docs/${page.relativePath}`,
-			title: page.title ?? page.relativePath,
-			description: page.description ?? `Vitest docs page: ${page.relativePath}`,
-			mimeType: "text/markdown",
-			...page.annotations ? { annotations: toSdkAnnotations(page.annotations) } : {}
-		})) };
-	} }), {
-		title: "Vitest Documentation Page",
-		description: "A single page from the vendored vitest.dev docs.",
-		mimeType: "text/markdown"
-	}, async (uri, variables) => {
-		const path = variables.path;
-		const result = await readUpstreamDoc(vendorRoot, Array.isArray(path) ? path.join("/") : String(path));
-		return { contents: [{
-			uri: uri.href,
-			mimeType: result.mimeType,
-			text: result.content
-		}] };
-	});
-	server.registerResource("vitest_agent_patterns_index", "vitest-agent://patterns/", {
-		title: "vitest-agent patterns: index",
-		description: "Use first when you need a curated vitest-agent pattern and want to discover what's available — lists every pattern slug with its title and one-line summary so you can pick the right `vitest-agent://patterns/<slug>` URI before fetching.",
-		mimeType: "text/markdown"
-	}, async (uri) => {
-		const result = await renderPatternsIndex(patternsRoot);
-		return { contents: [{
-			uri: uri.href,
-			mimeType: result.mimeType,
-			text: result.content
-		}] };
-	});
-	server.registerResource("vitest_agent_pattern", new ResourceTemplate("vitest-agent://patterns/{slug}", { list: async () => {
-		return { resources: (await listPatternEntries(patternsRoot)).map((p) => ({
-			name: `vitest_agent_pattern_${p.slug.replace(/[^A-Za-z0-9]/g, "_")}`,
-			uri: `vitest-agent://patterns/${p.slug}`,
-			title: p.title,
-			description: p.summary,
-			mimeType: "text/markdown",
-			...p.annotations ? { annotations: toSdkAnnotations(p.annotations) } : {}
-		})) };
-	} }), {
-		title: "vitest-agent Pattern",
-		description: "A single curated pattern from the vitest-agent project.",
-		mimeType: "text/markdown"
-	}, async (uri, variables) => {
-		const slug = variables.slug;
-		const result = await readPattern(patternsRoot, Array.isArray(slug) ? slug[0] : String(slug));
-		return { contents: [{
-			uri: uri.href,
-			mimeType: result.mimeType,
-			text: result.content
-		}] };
-	});
-}
-
-//#endregion
-export { registerAllResources, resolveContentRoots };

package/resources/indexes.js

@@ -1,77 +0,0 @@
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-
-//#region src/resources/indexes.ts
-async function listMarkdownPages(root) {
-	const out = [];
-	async function walk(rel) {
-		const entries = await readdir(join(root, rel), { withFileTypes: true });
-		for (const entry of entries) {
-			if (entry.name.startsWith(".") || entry.name.startsWith("_")) continue;
-			const next = rel ? `${rel}/${entry.name}` : entry.name;
-			if (entry.isDirectory()) await walk(next);
-			else if (entry.isFile() && entry.name.endsWith(".md") && entry.name !== "ATTRIBUTION.md") out.push(next.replace(/\.md$/, ""));
-		}
-	}
-	await walk("");
-	out.sort();
-	return out;
-}
-async function renderUpstreamIndex(vendorRoot) {
-	const manifestRaw = await readFile(join(vendorRoot, "manifest.json"), "utf8");
-	const manifest = JSON.parse(manifestRaw);
-	const pages = await listMarkdownPages(vendorRoot);
-	const grouped = /* @__PURE__ */ new Map();
-	for (const page of pages) {
-		const slash = page.indexOf("/");
-		const section = slash === -1 ? "root" : page.slice(0, slash);
-		const list = grouped.get(section) ?? [];
-		list.push(page);
-		grouped.set(section, list);
-	}
-	const lines = [];
-	lines.push("# Vitest Documentation (Upstream Snapshot)");
-	lines.push("");
-	lines.push(`Snapshotted from [vitest-dev/vitest](https://github.com/vitest-dev/vitest) at tag \`${manifest.tag}\` (commit \`${manifest.commitSha.slice(0, 12)}\`).`);
-	lines.push("");
-	lines.push("Fetch any page by URI: `vitest://docs/<path>` (e.g., `vitest://docs/api/mock`).");
-	lines.push("");
-	const sections = [...grouped.keys()].sort();
-	for (const section of sections) {
-		lines.push(`## ${section}`);
-		lines.push("");
-		for (const page of grouped.get(section) ?? []) {
-			const display = page.startsWith(`${section}/`) ? page.slice(section.length + 1) : page;
-			lines.push(`- \`vitest://docs/${page}\` — ${display}`);
-		}
-		lines.push("");
-	}
-	return {
-		content: lines.join("\n"),
-		mimeType: "text/markdown"
-	};
-}
-async function renderPatternsIndex(patternsRoot) {
-	const metaRaw = await readFile(join(patternsRoot, "_meta.json"), "utf8");
-	const meta = JSON.parse(metaRaw);
-	const lines = [];
-	lines.push("# vitest-agent Curated Patterns");
-	lines.push("");
-	lines.push("Hand-written patterns specific to the vitest-agent project. Fetch any pattern by URI: `vitest-agent://patterns/<slug>`.");
-	lines.push("");
-	for (const pattern of meta.patterns) {
-		lines.push(`## ${pattern.title}`);
-		lines.push("");
-		lines.push(pattern.summary);
-		lines.push("");
-		lines.push(`- URI: \`vitest-agent://patterns/${pattern.slug}\``);
-		lines.push("");
-	}
-	return {
-		content: lines.join("\n"),
-		mimeType: "text/markdown"
-	};
-}
-
-//#endregion
-export { renderPatternsIndex, renderUpstreamIndex };

package/resources/manifest-schema.js

@@ -1,46 +0,0 @@
-import { Schema } from "effect";
-
-//#region src/resources/manifest-schema.ts
-const RELATIVE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
-/**
-* MCP 2025-11-25 resource annotations. Both sub-fields are optional so a
-* partially-annotated manifest decodes cleanly during an editorial pass.
-*
-* `audience` is the set of client roles a resource is relevant to; today
-* only `assistant` is meaningful for the vitest-agent MCP server.
-* `priority` is a float in [0, 1] that lets a client rank or filter
-* results before pulling content into context. See the editorial guide
-* in `docs/superpowers/specs/2.0-resource-annotations.md` for the
-* priority bands per content type.
-*/
-const ResourceAnnotations = Schema.Struct({
-	audience: Schema.optional(Schema.Array(Schema.Literal("user", "assistant"))),
-	priority: Schema.optional(Schema.Number.pipe(Schema.between(0, 1)))
-});
-const ManifestPage = Schema.Struct({
-	path: Schema.String.pipe(Schema.pattern(RELATIVE_PATH)),
-	title: Schema.NonEmptyString,
-	description: Schema.NonEmptyString,
-	annotations: Schema.optional(ResourceAnnotations)
-});
-const UpstreamManifest = Schema.Struct({
-	tag: Schema.NonEmptyString,
-	commitSha: Schema.NonEmptyString,
-	capturedAt: Schema.NonEmptyString,
-	source: Schema.NonEmptyString,
-	pages: Schema.optional(Schema.Array(ManifestPage))
-});
-const decodeUpstreamManifest = Schema.decodeUnknown(UpstreamManifest);
-const encodeUpstreamManifest = Schema.encodeUnknown(UpstreamManifest);
-const SLUG_PATTERN = /^[A-Za-z0-9._]+(?:[/-][A-Za-z0-9._]+)*$/;
-const PatternEntry = Schema.Struct({
-	slug: Schema.String.pipe(Schema.pattern(SLUG_PATTERN)),
-	title: Schema.NonEmptyString,
-	summary: Schema.NonEmptyString,
-	annotations: Schema.optional(ResourceAnnotations)
-});
-const PatternsManifest = Schema.Struct({ patterns: Schema.Array(PatternEntry) });
-const decodePatternsManifest = Schema.decodeUnknown(PatternsManifest);
-
-//#endregion
-export { ManifestPage, PatternEntry, PatternsManifest, ResourceAnnotations, UpstreamManifest, decodePatternsManifest, decodeUpstreamManifest };

package/resources/paths.js

@@ -1,20 +0,0 @@
-import { isAbsolute, normalize, resolve, sep } from "node:path";
-
-//#region src/resources/paths.ts
-/**
-* Resolves a user-provided relative path against a vendored root,
-* appending `.md` if missing and rejecting traversal attempts.
-*/
-function resolveResourcePath(root, relativePath) {
-	if (relativePath === "") return root;
-	if (relativePath.includes("\0")) throw new Error("path contains null byte");
-	if (isAbsolute(relativePath)) throw new Error("absolute path not allowed");
-	const stripped = relativePath.replace(/^\/+/, "");
-	const resolved = resolve(root, normalize(stripped.endsWith(".md") ? stripped : `${stripped}.md`));
-	const rootWithSep = root.endsWith(sep) ? root : `${root}${sep}`;
-	if (!resolved.startsWith(rootWithSep) && resolved !== root) throw new Error("path escapes vendor root");
-	return resolved;
-}
-
-//#endregion
-export { resolveResourcePath };

package/resources/patterns.js

@@ -1,22 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-
-//#region src/resources/patterns.ts
-const SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
-async function readPattern(patternsRoot, slug) {
-	if (!SLUG_PATTERN.test(slug)) throw new Error(`invalid slug: ${slug}`);
-	const absPath = join(patternsRoot, `${slug}.md`);
-	try {
-		return {
-			content: await readFile(absPath, "utf8"),
-			mimeType: "text/markdown"
-		};
-	} catch (err) {
-		const code = err.code;
-		if (code === "ENOENT" || code === "EISDIR") throw new Error(`pattern not found: ${slug}. See vitest-agent://patterns/ for the index.`);
-		throw err;
-	}
-}
-
-//#endregion
-export { readPattern };

package/resources/upstream-docs.js

@@ -1,22 +0,0 @@
-import { resolveResourcePath } from "./paths.js";
-import { readFile } from "node:fs/promises";
-
-//#region src/resources/upstream-docs.ts
-async function readUpstreamDoc(vendorRoot, relativePath) {
-	const absPath = resolveResourcePath(vendorRoot, relativePath);
-	let content;
-	try {
-		content = await readFile(absPath, "utf8");
-	} catch (err) {
-		const code = err.code;
-		if (code === "ENOENT" || code === "EISDIR") throw new Error(`upstream doc not found: ${relativePath}`);
-		throw err;
-	}
-	return {
-		content,
-		mimeType: "text/markdown"
-	};
-}
-
-//#endregion
-export { readUpstreamDoc };

package/vendor/vitest-docs/ATTRIBUTION.md

@@ -1,5 +0,0 @@
-# Attribution
-
-The markdown files under `vendor/vitest-docs/` are vendored from the [Vitest project](https://github.com/vitest-dev/vitest) under the MIT License.
-
-See `manifest.json` for the exact upstream tag and commit SHA captured.

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

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