Skip to main content
Glama

Debug Test Case

debug_testcase
Read-only

Analyze failing or flaky tests to get execution history, failure patterns, common error messages, and AI-assisted root-cause suggestions for debugging.

Instructions

AI-assisted root cause analysis for a failing or flaky test. Returns historical execution data, aggregated failure patterns (error types, frequency, browsers affected), common error messages, and a debugging_prompt field (the TestDino debugging checklist, the same for every test). If you are debugging a failing test, call get_debug_evidence first: it already carries the debugging rules, the verdict and the artifact links. Come here afterwards only for the stored AI suggestions or the full execution history. Read debugging_prompt before drawing conclusions: it says how to read the history and when a cause is proven. Any fixes you produce from this analysis are recommendations only — validate them against the live code before applying. Use this when the user asks "why is test X failing?", "debug test X", or "is test X flaky?". Identify the test by testcase_id (its pw_test_id, exact) or testcase_name (its title). A title can match several tests (the same test under several Playwright projects, or the same title in several files): pair it with playwright_project and/or suite_file_path. If the response is 409 AMBIGUOUS_IDENTITY, its candidates name the Playwright project of each — call again with playwright_project set to the one you mean, or testcase_id set to its pw_test_id. Set include_ai_insights=true to also get TestDino's stored AI analysis under ai_fixes (recommendations and quick fixes, often with code), for the most recent failing execution or the testrun_id you pass. AI payloads are generated lazily: while an ai_fixes section reports "in_progress", poll get_ai_insights(testrun_id=..., testcase_id=...) until it reports "completed". An "unavailable" section carries the upstream statusCode: retry a 5xx or timeout once via get_ai_insights; a 4xx (bad ids) is final.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projectId": "<projectId>"
    },
    "name": "debug_testcase"
  }
}

Input Schema

NameRequiredDescriptionDefault
projectIdYesProject ID
testrun_idNoOnly with include_ai_insights: fetch the AI analysis for this specific run instead of the most recent failure.
testcase_idNoThe test's pw_test_id — exact, never ambiguous. Wins over testcase_name and suite_file_path.
testcase_nameNoTest case name / title to debug. Required unless testcase_id is given.
suite_file_pathNoOptional spec file path — disambiguates when several tests share the same title in different files. A path with leading folders or only the file name also matches. Example: "tests/checkout.spec.ts".
playwright_projectNoOptional Playwright project name (from playwright.config, e.g. "chromium") — picks one test when the same title runs under several projects. Ignored with testcase_id.
include_ai_insightsNoAttach AI recommendations + quick fixes for this test under `ai_fixes` (targets the most recent failing execution unless testrun_id is set).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / playwright_project
      Added value: +{
      +  "description": "Optional Playwright project name (from playwright.config, e.g. \"chromium\") — picks one test when the same title runs under several projects. Ignored with testcase_id.",
      +  "type": "string"
      +}
    • changedInput schema / properties / suite_file_path / description
      Previous value: -"Optional spec file path — disambiguates when several tests share the same title. Example: \"tests/checkout.spec.ts\"."New value: +"Optional spec file path — disambiguates when several tests share the same title in different files. A path with leading folders or only the file name also matches. Example: \"tests/checkout.spec.ts\"."
  2. Changed9 schema fields changedv2.2.0
    • addedInput schema / $schema
      Added value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / include_ai_insights / description
      Previous value: -"Attach AI recommendations + quick fixes for this test under `ai_fixes` (targets the most recent failing execution unless testrun_id is set). If a section reports `in_progress`, poll get_ai_insights(testrun_id=..., testcase_id=...) instead of re-calling this tool."New value: +"Attach AI recommendations + quick fixes for this test under `ai_fixes` (targets the most recent failing execution unless testrun_id is set)."
    • changedInput schema / properties / projectId / description
      Previous value: -"Project ID (Required). The TestDino project identifier."New value: +"Project ID"
    • changedInput schema / properties / suite_file_path / description
      Previous value: -"Optional spec file path to disambiguate when several tests share the same title. Example: 'tests/checkout.spec.ts'."New value: +"Optional spec file path — disambiguates when several tests share the same title. Example: \"tests/checkout.spec.ts\"."
    • addedInput schema / properties / testcase_id
      Added value: +{
      +  "description": "The test's pw_test_id — exact, never ambiguous. Wins over testcase_name and suite_file_path.",
      +  "type": "string"
      +}
    • changedInput schema / properties / testcase_name / description
      Previous value: -"Test case name/title to debug (Required). Example: 'Verify user can logout and login'."New value: +"Test case name / title to debug. Required unless testcase_id is given."
    • changedInput schema / properties / testrun_id / description
      Previous value: -"Only with include_ai_insights: target the AI fixes at this specific run instead of the most recent failure."New value: +"Only with include_ai_insights: fetch the AI analysis for this specific run instead of the most recent failure."
    • changedInput schema / required
      Previous value: -[
      -  "projectId",
      -  "testcase_name"
      -]New value: +[
      +  "projectId"
      +]
  3. Changed3 schema fields changedv2.0.2
    • addedInput schema / properties / include_ai_insights
      Added value: +{
      +  "description": "Attach AI recommendations + quick fixes for this test under `ai_fixes` (targets the most recent failing execution unless testrun_id is set). If a section reports `in_progress`, poll get_ai_insights(testrun_id=..., testcase_id=...) instead of re-calling this tool.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / suite_file_path
      Added value: +{
      +  "description": "Optional spec file path to disambiguate when several tests share the same title. Example: 'tests/checkout.spec.ts'.",
      +  "type": "string"
      +}
    • addedInput schema / properties / testrun_id
      Added value: +{
      +  "description": "Only with include_ai_insights: target the AI fixes at this specific run instead of the most recent failure.",
      +  "type": "string"
      +}
  4. First observed

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds real value on top by warning that generated fixes are recommendations only and must be validated against live code, and by explaining the 409 AMBIGUOUS_IDENTITY candidate/retry flow and the ai_fixes lifecycle states. The gap is that it never says what the historical execution payload looks like in shape or volume (pagination, time window), so the agent cannot anticipate response size.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the get_debug_evidence routing rule are front-loaded, and nearly every sentence carries operational content. It is a single undifferentiated block, though, and the ambiguity handling is restated in the prose after already appearing in the testcase_name and playwright_project schema descriptions, so a tighter edit would lose nothing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter read tool with no output schema, the description covers return contents, error-state semantics, polling behavior, precedence rules, and the caveat that its output is advisory. There is no output schema, yet the description names the ai_fixes section and its in_progress/unavailable states, which is exactly the compensation needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description earns above baseline by stating precedence (testcase_id wins over testcase_name and suite_file_path, playwright_project is ignored with testcase_id) and by tying testrun_id to include_ai_insights as a conditional pairing. It also explains why a bare title is risky and how the 409 candidates map back to playwright_project, which the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('AI-assisted root cause analysis for a failing or flaky test') and enumerates what comes back: historical execution data, aggregated failure patterns by error type/frequency/browser, common error messages, and the debugging_prompt. It explicitly contrasts itself with the sibling get_debug_evidence, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit trigger phrases ('why is test X failing?', 'is test X flaky?'), an explicit ordering rule (call get_debug_evidence first; come here only for stored AI suggestions or full history), and a fallback path (poll get_ai_insights on in_progress, retry once on 5xx but not 4xx). Nothing about when to select this tool is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.