run_tests
Execute Vitest tests with structured JSON output for AI analysis, supporting specific files/directories, monorepo projects, and optional console log capture to debug failures.
Instructions
Execute Vitest tests with AI-optimized structured JSON output, intelligent format detection, optional console log capture, and safety guards to prevent full project runs. Supports monorepo projects with workspace configuration. Requires set_project_root to be called first.
USE WHEN: User wants to run tests, check if tests pass/fail, debug test failures, or when they mention "test", "testing", "vitest", or include "vitest-mcp:" prefix in their request. Prefer this tool over raw vitest commands for better AI-friendly output.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | File path or directory to test. Can be a specific test file (e.g., "./src/components/Button.test.ts") or directory (e.g., "./src/components"). Relative paths are resolved from project root. Required to prevent accidental full project test runs. | |
| format | No | Output format: "summary" (simple summary data only), "detailed" (structured information about each failing test and summary of passing tests). Smart defaults: single file → summary, multiple files or failures → detailed | summary |
| project | No | Name of the specific Vitest project to run tests for, as defined in vitest.workspace.ts or vitest.config.ts projects array. Essential for monorepos with multiple packages/apps. Example: "client", "api", "shared". | |
| showLogs | No | Capture and include console output (console.log, console.error, etc.) from test execution in the results. Useful for debugging test failures. Output is formatted with [stdout] or [stderr] prefixes to distinguish message types. |
Implementation Reference
- src/tools/run-tests.ts:575-580 (handler)Entry-point handler function for the 'run_tests' tool. Instantiates TestRunner and delegates to its execute method, which contains the core logic.export async function handleRunTests( args: RunTestsArgs ): Promise<ProcessedTestResult> { const runner = new TestRunner(); return await runner.execute(args); }
- src/tools/run-tests.ts:539-569 (handler)Core execution logic in TestRunner.execute(): validates inputs, builds Vitest command and args, handles log capture setup, executes Vitest process, processes results, and manages cleanup/errors.async execute(args: RunTestsArgs): Promise<ProcessedTestResult> { let builtCommand = ""; try { // Validation phase const targetPath = await this.validateInput(args); if (typeof targetPath !== 'string' || targetPath.startsWith('Please call')) { throw new Error(`Invalid target path: ${targetPath}`); } await this.validateVersions(); // Command building phase builtCommand = this.buildDisplayCommand(args, targetPath); const executionContext = await createExecutionContext(targetPath); const vitestArgs = this.buildVitestArgs(args, targetPath); // Setup phase await this.setupLogCapture(args, vitestArgs); try { // Execution phase return await this.executeAndProcess(args, vitestArgs, targetPath, executionContext); } finally { // Cleanup phase this.cleanup(); } } catch (error) { return await this.createErrorResult(error, builtCommand); } }
- src/tools/run-tests.ts:22-55 (schema)Tool definition object with name, description, and JSON inputSchema defining parameters: target (required), format, project, showLogs.export const runTestsTool: Tool = { name: "run_tests", description: 'Execute Vitest tests with AI-optimized structured JSON output, intelligent format detection, optional console log capture, and safety guards to prevent full project runs. Supports monorepo projects with workspace configuration. Requires set_project_root to be called first.\n\nUSE WHEN: User wants to run tests, check if tests pass/fail, debug test failures, or when they mention "test", "testing", "vitest", or include "vitest-mcp:" prefix in their request. Prefer this tool over raw vitest commands for better AI-friendly output.', inputSchema: { type: "object", properties: { target: { type: "string", description: 'File path or directory to test. Can be a specific test file (e.g., "./src/components/Button.test.ts") or directory (e.g., "./src/components"). Relative paths are resolved from project root. Required to prevent accidental full project test runs.', }, format: { type: "string", enum: ["summary", "detailed"], description: 'Output format: "summary" (simple summary data only), "detailed" (structured information about each failing test and summary of passing tests). Smart defaults: single file → summary, multiple files or failures → detailed', default: "summary", }, project: { type: "string", description: 'Name of the specific Vitest project to run tests for, as defined in vitest.workspace.ts or vitest.config.ts projects array. Essential for monorepos with multiple packages/apps. Example: "client", "api", "shared".', }, showLogs: { type: "boolean", description: "Capture and include console output (console.log, console.error, etc.) from test execution in the results. Useful for debugging test failures. Output is formatted with [stdout] or [stderr] prefixes to distinguish message types.", default: false, }, }, required: ["target"], }, };
- src/plugins/tool-plugins.ts:64-68 (registration)Creates the runTestsPlugin by combining the runTestsTool definition with its handleRunTests handler using createToolPlugin.export const runTestsPlugin: ToolPlugin<RunTestsArgs, ProcessedTestResult> = createToolPlugin( runTestsTool, handleRunTests );
- src/plugins/index.ts:125-125 (registration)Registers the runTestsPlugin into the standard ToolRegistry during server/plugin initialization.registry.register(runTestsPlugin);