list_tests
Discover and catalog test files across your project by recursively searching directories with support for common test file patterns like .test.* and .spec.*. Use this tool to understand test organization and coverage scope.
Instructions
Discover and catalog test files across the project with support for common test file patterns (.test., .spec.). Recursively searches directories and provides structured file information including paths and relative locations. Useful for understanding test organization and coverage scope. Requires set_project_root to be called first.
USE WHEN: User wants to explore test structure, find test files, understand test organization, or asks "what tests exist", "show me test files", or mentions exploring/finding tests. Also use when "vitest-mcp:" prefix is included and context involves test discovery.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Optional directory path to search for test files. Can be relative (e.g., "./src/components") or absolute. If not provided, searches the entire project root. Useful for limiting search scope to specific directories or modules. |
Implementation Reference
- src/tools/list-tests.ts:42-82 (handler)Core handler function that implements the list_tests tool logic: validates project root and search path, discovers test files using findTestFiles utility, and returns structured results.export async function handleListTests( args: ListTestsArgs ): Promise<ListTestsResult> { try { let projectRoot: string; try { projectRoot = projectContext.getProjectRoot(); } catch { throw new Error("Please call set_project_root first"); } const searchPath = args.path ? resolve(projectRoot, args.path) : projectRoot; if (!(await fileExists(searchPath))) { throw new Error(`Search path does not exist: ${searchPath}`); } if (!(await isDirectory(searchPath))) { throw new Error(`Search path is not a directory: ${searchPath}`); } const testFiles = await findTestFiles(searchPath); return { testFiles: testFiles.map((file) => ({ path: file.path, relativePath: file.relativePath, })), totalCount: testFiles.length, searchPath, projectRoot, }; } catch (error) { throw new Error( `Failed to list test files: ${ error instanceof Error ? error.message : "Unknown error" }` ); } }
- src/tools/list-tests.ts:9-23 (schema)Tool specification defining the list_tests tool, including name, detailed description, and inputSchema for optional path parameter.export const listTestsTool: Tool = { name: "list_tests", description: 'Discover and catalog test files across the project with support for common test file patterns (.test.*, .spec.*). Recursively searches directories and provides structured file information including paths and relative locations. Useful for understanding test organization and coverage scope. Requires set_project_root to be called first.\n\nUSE WHEN: User wants to explore test structure, find test files, understand test organization, or asks "what tests exist", "show me test files", or mentions exploring/finding tests. Also use when "vitest-mcp:" prefix is included and context involves test discovery.', inputSchema: { type: "object", properties: { path: { type: "string", description: 'Optional directory path to search for test files. Can be relative (e.g., "./src/components") or absolute. If not provided, searches the entire project root. Useful for limiting search scope to specific directories or modules.', }, }, }, };
- src/tools/list-tests.ts:25-37 (schema)TypeScript interfaces defining input (ListTestsArgs) and output (ListTestsResult) structures for the list_tests tool.export interface ListTestsArgs { path?: string; } export interface ListTestsResult { testFiles: Array<{ path: string; relativePath: string; }>; totalCount: number; searchPath: string; projectRoot: string; }
- src/plugins/tool-plugins.ts:54-58 (registration)Plugin registration: creates listTestsPlugin by wrapping listTestsTool and handleListTests with createToolPlugin for the MCP plugin architecture.export const listTestsPlugin: ToolPlugin<ListTestsArgs, ListTestsResult> = createToolPlugin( listTestsTool, handleListTests );
- src/plugins/index.ts:123-126 (registration)Final registration of listTestsPlugin (and other standard plugins) to the ToolRegistry in the createStandardToolRegistry factory function.registry.register(setProjectRootPlugin); registry.register(listTestsPlugin); registry.register(runTestsPlugin); registry.register(analyzeCoveragePlugin);