list_tests
Explore and catalog test files in your project using supported patterns (.test., .spec.). Recursively searches directories, providing structured file details like paths and relative locations. Ideal for understanding test organization and identifying 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
| 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. |
Input Schema (JSON Schema)
{
"properties": {
"path": {
"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.",
"type": "string"
}
},
"type": "object"
}
Implementation Reference
- src/tools/list-tests.ts:42-82 (handler)The main execution handler for the 'list_tests' tool. Resolves the search path relative to project root, validates it exists and is a directory, finds test files recursively, and returns structured results with absolute/relative paths and count.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:25-37 (schema)TypeScript interfaces defining the input arguments (optional path) and output result structure (test files list with paths, count, search path, project root) 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/tools/list-tests.ts:9-23 (registration)Tool definition object for 'list_tests' including name, detailed description, and input schema for MCP protocol compliance.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/plugins/tool-plugins.ts:54-58 (registration)Creates the ToolPlugin instance for list_tests by combining the tool definition and handler using the plugin factory.export const listTestsPlugin: ToolPlugin<ListTestsArgs, ListTestsResult> = createToolPlugin( listTestsTool, handleListTests );
- src/plugins/index.ts:122-126 (registration)Final registration of the listTestsPlugin into the central ToolRegistry during standard registry creation, making the tool available to the MCP server.// Register all standard plugins registry.register(setProjectRootPlugin); registry.register(listTestsPlugin); registry.register(runTestsPlugin); registry.register(analyzeCoveragePlugin);