Docs

TestDino MCP — AI Agent Skills Guide

How to use this guide: Read this document before making any TestDino tool calls. It tells you which tool to pick, what parameters are required vs. optional, and how to chain tools together for common tasks.

Table of Contents

1. Core Concepts
2. Tool Reference
   • Automated test analytics
     • health
     • list_testruns
     • get_run_details
     • list_testcase
     • get_testcase_details
     • debug_testcase
     • get_run_error_clusters
     • get_audit_report and submit_audit_report
   • Manual test cases
     • list_manual_test_cases
     • get_manual_test_case
     • create_manual_test_case
     • update_manual_test_case
     • list_manual_test_suites
     • create_manual_test_suite
   • Releases (a.k.a. milestones)
     • list_releases
     • get_release
     • create_release
     • update_release
   • Manual test runs
     • list_manual_runs
     • get_manual_run
     • create_manual_run
     • update_manual_run
     • list_run_test_cases
     • update_run_test_case
   • Exploratory sessions
     • list_sessions
     • get_session
     • create_session
     • update_session
   • Integrations (issue trackers)
     • connect_integration
     • get_integration_status
     • create_external_issue
     • get_external_issue
3. Workflows & Patterns
4. Decision Trees
5. Parameter Quick Reference
6. Error Handling

Core Concepts

Authentication

• All tools read TESTDINO_PAT automatically from the environment — you never pass it as a parameter.
• If this variable is missing, all tools throw "Missing TESTDINO_PAT environment variable". Tell the user to add it to their mcp.json env section.

projectId

• Required for every tool except health.
• Call health() first in any session to get the project IDs and pick the right one.
• Projects are nested under organizations in the health response.

Identifiers

• testrun_id: A string MongoDB-style ID (e.g. "test_run_6901b2abc6b187e63f536a6b")
• counter: A sequential integer (e.g. 43) — human-readable alias for a test run
• testcase_id: A string ID for a specific test case execution
• caseId: A string ID or human-readable ID (e.g. "TC-123") for a manual test case
• releaseId: Either an internal tcm_milestone_... _id or a counter-style ID like "MS-12". The MCP layer resolves the counter form automatically.
• runId: Either an internal tcm_run_... _id or a counter-style ID like "RUN-12". Counter form resolves the same way.
• sessionId: Either an internal tcm_session_... _id or a counter-style ID like "SES-12".
• rtcRef (per-case record in a run): One of three forms accepted by update_run_test_case:
  1. The internal tcm_rtc_... _id of the run-test-case row.
  2. The caseKey (e.g. "TC-156") — what the UI shows in the ID column.
  3. The underlying manual test case _id. Works even when no run-test-case row exists yet (untested virtual cases) — the server creates the record on first edit.
• assigneeUserId: Accepted as either a User _id ("user_...") or an email address. Server resolves email to _id automatically. Used in create_session, update_session, update_run_test_case, and as a filter in list_sessions/list_run_test_cases.

Pagination defaults

• Most list tools default to limit=20 or limit=50. Page through results rather than pulling everything at once.
• Prefer filters over fetching everything.

Canonical values for state / type / result

Some free-text fields drive the UI's color/badge map and have a canonical stored form that's lowercase + underscore-joined:

• state on sessions and runs: new, under_review, in_progress, on_hold, done, rejected, …
• type on releases: iteration, major, minor, patch, …
• result / status on run test cases: untested, passed, failed, blocked, skipped, retest.

You can pass either the canonical form or the display form ("Under review", "Iteration", "Passed") — the server normalizes to canonical before storing. If you pass display form and the UI badge ever looks dull/grey, that means normalization didn't run; report the input to the user. The canonical form for result values is past tense ("passed", not "pass").

Arrays vs comma-separated strings

When sending payloads (POST/PATCH bodies), tags and linkedIssues MUST be JSON arrays — ["smoke","regression"], not "smoke,regression". The comma-separated form is only accepted on list-tool query-filter parameters because URLs can't carry arrays cleanly. Mixing these up returns a 400 from zod.

Test Audit Principle: Two Scenarios

The audit flow (get_audit_report + submit_audit_report) is triggered by a named request only. There are exactly two scenarios:

Scenario 1: Generic audit request (any kind) → DO NOT call the audit tools, DO NOT mention TestDino

When the user asks for any kind of audit without explicitly naming TestDino, e.g. "audit this", "run a test audit", "audit this file", "security audit", "code review", "accessibility audit", "audit our tests", run the audit as a normal AI-agent conversation. Read the target, give your review, findings, and suggestions directly in chat.

This applies even when the target is Playwright test code. A generic "test audit" on a Playwright file is still just a normal audit conversation. The tool is not triggered unless the user explicitly names TestDino.

Do NOT say "TestDino's audit is Playwright-only", "I can run a TestDino audit instead", or anything that mentions TestDino. Behave exactly as a plain AI assistant with no TestDino MCP installed.

Scenario 2: Explicit TestDino audit request → call get_audit_report (Playwright only)

Trigger phrases (any of these REQUIRE an immediate tool call): "TestDino test audit", "Testdino Test Audit", "Testdino audit", "TestDino MCP audit", "run a TestDino test audit", "audit this with TestDino", "I need a TestDino audit", "testdino test audit on this". Case-insensitive.

Mandatory behavior when triggered (Playwright target + TestDino named):

The moment a trigger phrase is detected, your first and immediate action MUST be get_audit_report(action="context", projectId=..., branch=...). Before that call returns:

• Do NOT write any audit content in chat.
• Do NOT produce a heading like "TestDino Test Audit: ".
• Do NOT list findings, score, severity, or recommendations.
• Do NOT describe the file in audit-report language.
• Do NOT simulate a TestDino audit from your own analysis.

Doing any of the above without calling the tool is a protocol violation. You would be claiming to produce a TestDino audit without actually running TestDino's audit flow. TestDino audits require the server-curated prompt and branch signals returned by action="context"; you do not have those without the tool call. "TestDino Test Audit" is the name of a capability that runs via this tool, not a style of output you can imitate.

Gate: target must be Playwright code. Detect via any of:

• @playwright/test imports
• Playwright APIs in the file: page., browser., context., locator(, test(, test.describe(, test.beforeEach(, test.step(, expect(page), browserName, storageState, test.extend(
• A playwright.config.ts/playwright.config.js in the repo
• .spec.ts/.spec.js/.test.ts/.test.js files using the above APIs
• The user explicitly naming Playwright

If the user names TestDino but the target is NOT Playwright, politely explain TestDino's test audit only covers Playwright automated test code and offer a regular (non-TestDino) audit instead. Do NOT call the tool. This is the one place mentioning TestDino's Playwright-only scope is appropriate, because the user explicitly invoked TestDino.

When both conditions hold (explicit TestDino + Playwright target), run the full flow:

1. get_audit_report(action="context", projectId=..., branch="...") is the IMMEDIATE first action. Use health() first if you don't have a projectId yet. orgId (needed for step 3) comes from health() too.
2. Only after Step 1 returns, analyze the local Playwright code using the returned prompt + branch signals, and write the audit to a local markdown file (e.g. TEST-AUDIT.md).
3. Call submit_audit_report(projectId=..., orgId=..., score=..., findings=..., recommendations=..., markdownReportPath="TEST-AUDIT.md", branch=..., reportName=...) to submit the completed report to TestDino.

Other principles for Scenario 2:

• If the user names a slice like auth/login, dashboards, alerts, or one spec file, keep the audit centered on that slice instead of drifting into generic suite hygiene.
• If the audit tools return PROJECT_NOT_FOUND, auth, or access errors, stop and resolve projectId (and orgId if you need it for submission) with health() before continuing. Do not generate a pseudo-audit from local files alone.
• Keep raw code local and only send structured findings plus concise evidence.
• Use the returned branch signals to decide which files to inspect first.
• Avoid pasting long snippets when a metric, prevalence estimate, or file/line reference is enough.

Tool Reference

health

Purpose: Verify PAT, check connection, and retrieve project/organization info.

Required parameters: None

When to call:

• At the start of every session before using any other tool.
• When the user asks "what projects do I have?" or "check my connection."
• When you don't yet have a projectId.

Response includes:

• Account and email info
• List of organizations → each with a list of projects and their projectId values
• Access permissions per project

Pattern:

Call health()
→ Extract org name and project name the user is asking about
→ Store projectId for all subsequent calls in this session

list_testruns

Purpose: Browse test runs with flexible filters.

Required parameters: projectId

Optional filters:

Response includes: test run IDs, counters, passed/failed/skipped/flaky counts, branch, author, commit, environment, duration, timestamps.

Good uses:

• Find test runs to get IDs for follow-up calls
• Summarize test execution trends over time
• Identify which commits introduced failures

get_run_details

Purpose: Get the full breakdown of a single test run (or batch of up to 20).

Required parameters: projectId + (testrun_id OR counter)

Optional parameters:

Response includes: full summary, test statistics by status, error category breakdown, test suites, and all test cases in the run.

Workflow:

list_testruns() → get run IDs → get_run_details() for the specific run

list_testcase

Purpose: List and filter test cases across one or many test runs.

Required parameters: projectId + a run scope (a run identifier or a cross-run filter). Without a run scope the tool returns an empty result with a warning. page/limit are pagination within the scope, NOT run selectors.

Test run identification (use one approach):

Test case filters (combine freely):

Key insight: When you use by_branch, by_commit, etc., the tool internally finds matching test runs first and then returns their test cases. You don't need to call list_testruns first.

get_testcase_details

Purpose: Get full details of a specific test case — errors, stack traces, steps, console logs, and artifacts.

Required parameters: projectId + at least one search parameter from the list below.

Search parameters (provide at least one):

Scoping parameters:

Deprecated aliases (retained for backward compatibility — prefer the primary names above):

History and filtering:

Critical rules:

• testcase_name alone without a run context returns ALL executions of that test across runs. Always pair with testrun_id unless you want cross-run history.
• Use steps_filter='failed_only' when debugging to cut noise — only failed steps are returned.
• Use include_history=true + history_limit to track a test's pass/fail pattern over time.

debug_testcase

Purpose: AI-assisted root cause analysis using historical failure data.

Required parameters: projectId, testcase_name

Optional parameters:

What it returns:

• Historical execution data across many test runs
• Failure patterns (error types, frequency, browsers affected)
• Common error messages and code locations
• A debugging_prompt string — pre-formatted analysis instructions specifically designed for the AI to use as context when diagnosing the issue

How to use the response:

1. Read the debugging_prompt field — treat it as domain-specific instructions for your analysis.
2. Examine the historical failure data to identify patterns.
3. Look for: consistent error messages, browser-specific failures, time-of-day patterns, correlations with specific branches or commits.
4. Optionally follow up with get_testcase_details() (with steps_filter="failed_only") for a specific failing execution — the response includes error details, steps, and artifacts (screenshots, videos, traces).

When to call:

• User says "why is test X failing?" / "debug test X" / "is test X flaky?"
• You need to understand if a failure is consistent or intermittent.
• You need historical context before diving into a specific execution.

Pattern:

debug_testcase(projectId, "Verify user login")
→ Read debugging_prompt from response
→ Analyze historical data using the debugging_prompt as context
→ Identify pattern: always fails? flaky? browser-specific? recent regression?
→ Optionally: get_testcase_details(...)
→ Provide root cause analysis and fix suggestions

get_audit_report and submit_audit_report

Purpose: Run a single-pass audit of Playwright test quality using TestDino for prompt orchestration and your local AI agent for repository analysis. get_audit_report fetches context and browses past reports; submit_audit_report files the completed audit. Only triggered when the user explicitly names TestDino.

Trigger rule (explicit TestDino naming required, tool call is MANDATORY and IMMEDIATE):

• When the user uses a TestDino trigger phrase ("TestDino test audit", "Testdino Test Audit", "Testdino audit", "TestDino MCP audit", "run a TestDino audit", "audit this with TestDino", etc.) AND the target is Playwright code, your first action MUST be get_audit_report(action="context", ...). Do not write audit content in chat, do not produce a "TestDino Test Audit" heading, do not list findings or a score before the tool call. Simulating the audit output without calling the tool is a protocol violation.
• For any generic audit request ("audit this", "test audit", "code audit", "security audit", etc.) where the user does NOT name TestDino, DO NOT call these tools. Run a normal AI audit conversation instead, with zero TestDino mention. This applies even when the target is Playwright test code.
• When TestDino is explicitly named, the target code must be Playwright (detected via @playwright/test imports, Playwright APIs like page./browser./locator(/test.extend(/storageState, playwright.config.*, or .spec.ts/.spec.js/.test.ts/.test.js files using those APIs).
• If the user names TestDino but the target is not Playwright, politely explain that TestDino's test audit only covers Playwright automated test code and offer a regular (non-TestDino) audit instead. Do NOT call the tools.

get_audit_report (read)

Required parameters: projectId, action

Actions:

Common parameters:

submit_audit_report (write)

Required parameters: projectId, orgId, score, and one of markdownReport or markdownReportPath.

Resolve orgId via health() if you don't already have it.

Parameters:

How to use them well:

1. Start with get_audit_report(action="context", branch="...") to fetch the prompt, branch signals, and prior audit summary.
2. If the user named a feature/spec area, remember the smallest correct scope plus explicit target for the eventual submission. Inspect only that local slice plus its shared helpers/setup.
3. In scoped audits, spend most findings on feature-specific validation gaps and missing scenarios; generic waits/logging/duplication issues are secondary unless they materially invalidate confidence in that slice.
4. If a call fails because the project is missing or access is denied, call health() and resolve the right projectId (and orgId) before continuing. Do not write a fallback local-only audit and present it as a TestDino audit.
5. Convert the audit into score, findings, recommendations, choose a short reportName, and write the markdown report to a local file (e.g. TEST-AUDIT.md).
6. Submit the completed report with submit_audit_report(projectId=..., orgId=..., branch=..., reportName=..., score=..., markdownReportPath="TEST-AUDIT.md"). Set TESTDINO_MCP_WORKSPACE to your repo root if the MCP starts outside the project, or pass an absolute path. Use inline markdownReport only when a local file is not practical.
7. Use get_audit_report(action="list") to browse all saved reports (add branch="..." for branch-specific history), and get_audit_report(action="get", reportId="...", writeMarkdown=true) to save TEST-AUDIT.md locally when needed.

Token efficiency rules:

• Never upload full files.
• Prefer counts, ratios, clusters, and representative patterns.
• If 20 tests share a problem, say that once with prevalence.
• Let the branch signals drive the investigation order before broad scanning.

Pattern:

get_audit_report(action="context", branch="main")
→ Receive prompt + branchSignals + lastAudit
→ Read only the relevant auth/login files plus shared setup/helpers
→ Build score + findings + recommendations + reportName, then write TEST-AUDIT.md
→ submit_audit_report(projectId=..., orgId=..., branch="main", scope="feature", target={ featureName: "Auth / Login" }, reportName="Login Flow Tests", score=88, findings=[...], markdownReportPath="TEST-AUDIT.md")
→ Optionally: get_audit_report(action="list") or get_audit_report(action="get", reportId="<id>")

list_manual_test_cases

Purpose: Search and browse manual test cases.

Required parameters: projectId

Optional filters:

get_manual_test_case

Purpose: Get full details of a single manual test case including steps, preconditions, and metadata.

Required parameters: projectId, caseId

• caseId can be the internal _id or a human-readable ID like 'TC-123'.

create_manual_test_case

Purpose: Create a new manual test case.

Required parameters: projectId, title, suiteName

Always call list_manual_test_suites() first to find the exact suite name. The suiteName must match exactly.

Key optional parameters:

Classic step format:

{
  "action": "Click the login button",
  "expectedResult": "User is redirected to dashboard",
  "data": "Username: testuser@example.com",
  "attachments": ["https://example.com/step-screenshot.png"]
}

Gherkin step format:

{
  "event": "Given",
  "stepDescription": "the user is on the login page",
  "attachments": ["https://example.com/step-screenshot.png"]
}

• event must be one of: "Given", "When", "And", "Then", "But"

update_manual_test_case

Purpose: Modify fields of an existing manual test case. Send only the fields you want to change.

Required parameters: projectId, caseId, updates (object)

updates object fields (all optional — only include what you're changing):

Important: attachments uses a nested add/remove structure — you can add and remove in the same call:

{
  "attachments": {
    "add": ["https://example.com/new-screenshot.png"],
    "remove": ["old-attachment-id"]
  }
}

Step-level attachments are added by including attachments on a top-level step in updates.steps.

list_manual_test_suites

Purpose: Get the test suite hierarchy (folders/groups for organizing manual test cases).

Required parameters: projectId

Optional parameters:

Returns: Array of suites with id, name, parentSuiteId, and child count.

When to call: Before create_manual_test_case to get the exact suiteName to use.

create_manual_test_suite

Purpose: Create a new test suite (folder) for organizing test cases.

Required parameters: projectId, name

Optional parameters:

list_releases

Purpose: Browse releases (a.k.a. milestones) for a project. Each release groups runs + sessions and may nest under a parent release up to 3 levels deep.

Required parameters: projectId

Optional filters:

get_release

Purpose: Full details for one release — dates, status, parent/root hierarchy, rolled-up progress stats (run counts, test status breakdown across descendants), linked issues.

Required parameters: projectId, releaseId

• releaseId accepts either an internal tcm_milestone_… _id or a counter-style ID like "MS-12".

create_release

Purpose: Create a new release.

Required parameters: projectId, name

Optional parameters:

update_release

Purpose: Modify one release. Send only the fields you want to change inside updates.

Required parameters: projectId, releaseId, updates (object)

updates object accepts the same fields as create — including branch, environment, buildTarget, testers, and parentReleaseId. Type passed in display form ("Major") is normalized to canonical ("major") before save.

list_manual_runs

Purpose: Browse manual test runs in a project — the executions of grouped test cases against a build/environment.

Required parameters: projectId

Optional filters:

get_manual_run

Purpose: Full details for one run — name, status, environment, linked release, test stats (total / passed / failed / blocked / untested), contributors, attachments, linked issues.

Required parameters: projectId, runId

• runId accepts the internal tcm_run_… _id OR a counter-style ID like "RUN-12".

create_manual_run

Purpose: Create a new manual test run.

Required parameters: projectId, name

Key optional parameters:

update_manual_run

Purpose: Modify an existing run's metadata. Per-case results live in update_run_test_case (NOT here).

Required parameters: projectId, runId, updates (object)

updates accepts: name, note, environment, releaseId, state, forecast, tags, linkedIssues, attachments, links, selectionMode.

Closed runs are read-only EXCEPT for releaseId — so a closed run can be re-attached to a different release without re-opening it.

list_run_test_cases

Purpose: Get the per-case execution records inside a manual run — what the UI shows as rows in the run's test-case table. Each row carries the case identity (caseKey like "TC-156", title), current assignee, and current result.

Required parameters: projectId, runId

Optional filters:

When to call: Always before update_run_test_case — gives you the exact rtcRef (or just the caseKey) and the current state per case.

update_run_test_case

Purpose: Set the assignee and/or result for one test case inside a manual run — exactly what clicking "Assign to" + the result pill does in the UI.

Required parameters: projectId, runId, rtcRef, updates (object)

rtcRef accepts THREE forms:

1. tcm_rtc_… _id (existing run-test-case row)
2. "TC-156" (caseKey — the user-facing display ID)
3. Underlying manual test case _id

Works for untested "virtual" cases too. In an 'all'-mode run, cases with no record yet still show "Untested" in the UI — passing the caseKey or test case _id auto-creates the run-test-case row on first edit. Same path the UI takes on first click.

updates object fields — quick verdict and detailed modes are mutually exclusive (mixing an assignee with detailed fields is rejected server-side):

Quick verdict fields:

Detailed-mode fields:

For multiple cases: call this tool in parallel — one call per case. Don't try to batch in updates.

list_sessions

Purpose: Browse exploratory testing sessions.

Required parameters: projectId

Optional filters:

…(truncated)