debug_testcase

Instructions

Implementation Reference

• src/tools/testcases/debug-testcase.ts:37-90 (handler)

  The main handler function that executes the debug_testcase tool logic. Fetches historical test case data and debugging prompt from the API.

  export async function handleDebugTestCase(args?: DebugTestCaseArgs) {
    const token = getApiKey(args);
  
    if (!token) {
      throw new Error(
        "Missing TESTDINO_PAT (PAT) environment variable. " +
          "Please configure it in your .cursor/mcp.json file under the 'env' section."
      );
    }
  
    if (!args?.projectId) {
      throw new Error("projectId is required");
    }
  
    if (!args?.testcase_name) {
      throw new Error("testcase_name is required");
    }
  
    try {
      // Call the debug endpoint - API returns historical data and debugging_prompt
      const debugUrl = endpoints.debugTestCase({
        projectId: String(args.projectId),
        testcase_name: String(args.testcase_name),
      });
  
      const response = await apiRequestJson<unknown>(debugUrl, {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      });
  
      // Return the API response (includes historical data and debugging_prompt)
      const responseText = JSON.stringify(response, null, 2);
      const content: Array<{ type: string; text: string }> = [
        { type: "text", text: responseText },
      ];
  
      // If response contains screenshot/image attachments, instruct the agent to view them
      if (
        responseText.includes('"contentType": "image/') ||
        responseText.includes('"name": "screenshot"')
      ) {
        content.push({
          type: "text",
          text: "Screenshot images are available in the historical test data above. You should fetch and view the screenshot URLs in the attempts' attachments to visually inspect the application state at the time of each failure — this is critical for accurate root cause analysis.",
        });
      }
  
      return { content };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      throw new Error(`Failed to debug test case: ${errorMessage}`);
    }
  }

• src/tools/testcases/debug-testcase.ts:11-35 (schema)

  The DebugTestCaseArgs interface and the debugTestCaseTool object with its inputSchema defining the required parameters (projectId, testcase_name).

  interface DebugTestCaseArgs {
    projectId: string;
    testcase_name: string;
  }
  
  export const debugTestCaseTool = {
    name: "debug_testcase",
    description:
      "Fetch historical execution and failure data for a specific test case. Returns raw historical data with test run details (ID, counter, branch), test runs summary, and a debugging prompt from the API. Each execution includes its associated test run information (testRunId, testRunCounter, branch) to help correlate failures across different test runs and branches. The AI client will analyze the data to identify failure patterns, find root causes, and provide fix suggestions. Use this when you need to debug a failing test case. Example: 'Debug test case \"Verify user login\"'.",
    inputSchema: {
      type: "object",
      properties: {
        projectId: {
          type: "string",
          description: "Project ID (Required). The TestDino project identifier.",
        },
        testcase_name: {
          type: "string",
          description:
            "Test case name/title to debug (Required). Example: 'Verify user can logout and login'.",
        },
      },
      required: ["projectId", "testcase_name"],
    },
  };

• src/index.ts:105-130 (registration)

  The tool is registered in the tools array at src/index.ts and routed in the CallToolRequestSchema handler at lines 225-229.

    debugTestCaseTool,
    testAuditTool,
    listManualTestCasesTool,
    getManualTestCaseTool,
    createManualTestCaseTool,
    updateManualTestCaseTool,
    listManualTestSuitesTool,
    createManualTestSuiteTool,
    // Releases
    listReleasesTool,
    getReleaseTool,
    createReleaseTool,
    updateReleaseTool,
    // Manual runs
    listManualRunsTool,
    getManualRunTool,
    createManualRunTool,
    updateManualRunTool,
    listRunTestCasesTool,
    updateRunTestCaseTool,
    // Sessions
    listSessionsTool,
    getSessionTool,
    createSessionTool,
    updateSessionTool,
  ];

• src/lib/endpoints.ts:269-277 (helper)

  Endpoint helper function that builds the URL for the debug-testcase API call.

  debugTestCase: (params: {
    projectId: string;
    testcase_name: string;
  }): string => {
    const baseUrl = getBaseUrl();
    const { projectId, testcase_name } = params;
    const queryParams = new URLSearchParams({ testcase_name });
    return `${baseUrl}/api/mcp/${projectId}/debug-testcase?${queryParams.toString()}`;
  },