Tool Index
Connection
health
Verifies the server is running and validates your API token. Returns PAT validation status, connection status, organisation and project access, and available modules (Test runs, Test case management).
After running health, tell the assistant which organisation or project you are working on. The assistant resolves and stores the projectId, so you do not need to specify it in future tool calls.
No parameters required for this tool.
Example
Organization and project
These tools are read-only. In any of their responses, a section that reads{ status: "unavailable" } could not be loaded: treat it as unknown, never as zero or none.
get_org_details
Answers plan and quota questions for one organization: the plan, executions used and remaining with the reset date, seats and projects used against the plan, extra executions (top-ups) on offer and active, the executions each visible project used, and org test health.
Buying executions or changing the plan happens on the billing page, not through this tool.
Example
- “What plan are we on, and how many executions are left this month?”
get_project_details
Returns how a project is set up and doing in 1 call: health summary, executions used this period, connected integrations, branch to environment mapping, the branches, environments, and tags seen, the top 10 flakiest, slowest, most-failing, chronically failing, and slowing-down tests, tag health, and CI speed-up suggestions.
health.dataState tells the agent how to read the figures:
To drill into one test case, follow up with
get_testcase_details or list_testcase.
Example
- “How is the checkout project doing this week, and which tests are the flakiest?”
get_pull_requests
Lists pull requests from the project’s connected GitHub or GitLab repository with their latest test run, or returns 1 pull request in detail.
Example
- “Show the open pull requests and how their latest test runs did.”
Analysis
list_testruns
Lists runs with filtering by branch, environment, time window, author, and commit.
NoteFilters can be combined. Pagination uses
page and limit.get_run_details
Returns a full report for one run, including suite breakdowns, test cases, failure categories, rerun metadata, and raw JSON.
For a swarm run, is_swarm is true and the response adds per-machine results in machines[], machine_summary, and could_not_execute_specs. A non-empty could_not_execute_specs means some test cases never ran, whatever the counts say.
When a run has test cases that passed only on retry, the response also carries next_steps: a note that the run is green but its first attempt failed, and a pointer to list_testcase and debug_testcase for the test cases involved. The field is absent when there is nothing to point at.
Note* Provide
testrun_id or counter. Use counter when your team references runs by sequence number.get_run_error_clusters
Groups one run’s failing tests by shared error signature. Returns the clusters, an unclustered bucket, a per-category rollup, and totals.
Example
- “Cluster the failures in run #47 by error type.”
- “What are the common error signatures in the latest run’s flaky tests?”
list_testcase
Lists test cases across runs with both run-level and case-level filters.
How it works:
- Identifies matching runs (by run ID, counter, or run filters like branch and time)
- Returns test cases from those runs
- Applies case-level filters (status, tag, browser, error category, runtime, artifacts)
* Provide at least one:
by_testrun_id, counter, or a run filter like by_branch with by_time_interval.
Example
get_testcase_details
Fetches full debug context for a single test case, including retries and artifacts.
* Provide
testcase_id or testcase_name. Add testrun_id for the result from a specific run.
When a batch is too large for one answer, the result keeps the first test cases in order, adds a note to warnings, and lists the rest in remaining as { testcase_id, testrun_id, title }. Call the tool again for each remaining entry with its testcase_id and testrun_id.
Example
debug_testcase
Debugs a test case by aggregating historical execution and failure data across multiple runs.
* Provide
testcase_id or testcase_name. If a title matches several tests, the tool returns 409 AMBIGUOUS_IDENTITY with a candidate per match; call again with the testcase_id of the one you mean.
The tool provides:
- Root cause analysis: analyzes error messages, artifacts, stack traces, and error categories across historical runs
- Failure patterns: identifies common error categories, messages, and locations
- Fix recommendations: suggests fixes based on historical analysis and failure patterns
Debug with AI
These tools take a failing test from evidence to a verified fix. Start withget_debug_evidence, act on what it returns, then confirm the change held with verify_fix once a new test run lands.
Each one reads stored test data. None of them consume AI generation credits, and they work whether or not AI features are enabled for the project.
get_debug_evidence
Returns the flake verdict, the regression boundary, and download links for every stored artifact in one call. Start a failing-test investigation here.
The response carries 3 pieces of evidence:
- Flake verdict with the per-attempt failure signatures behind it
- Regression boundary: the last test run this test case passed, and the first one it failed
- Artifacts: trace, screenshots, and the expected, actual, and diff images on a visual failure
testcase_name or testcase_id. A fully qualified title such as Checkout > guest flow > applies a coupon is retried on its leaf title when the full string matches nothing. When neither identifier resolves, the response returns a recovery warning naming the next call, not an empty verdict.
Artifact links expire in minutes. Download what you need right away, then call the tool again to mint fresh links. An expired link is not a missing artifact.
- “Why is the checkout test failing in run #96?”
- “Get me the evidence for the failing SSO test, markdown format.”
get_flake_verdict
Compares a test case’s retry attempts within one test run and returns whether the failure repeats.
The signature behind each verdict combines the failing step, the error location, the error type and operation, the expected and received values, and the visual diff ratio. 2 timeouts on different calls produce different signatures rather than collapsing into one.
The verdict describes behavior, not cause. It reports which fixes the evidence rules out, and does not say where the fix goes. Decide that after reading the artifacts, the trace, and the code.
This needs a test case that ran with retries enabled. A single attempt is always
inconclusive. The verdict is computed from the stored attempts, so the same attempts always return the same answer.- “Is the flaky login test genuinely flaky, or is it actually broken?”
verify_fix
Splits a test case’s run history at a baseline test run and compares what happened after against what happened before. Call it after a new test run lands.
A test case that passes only on a retry returns
unstable, never fixed. An unchanged error means the fix missed, not that the test case is flaky.
The baseline must be a test run this test case actually executed in. An ID from another project or another test case is rejected rather than answered against the wrong test run.
Example
- “I pushed the fix and run #104 just finished. Did it hold?”
Re-run
These tools re-run a finished test run’s failed or flaky test cases.get_rerun_selection decides what would run and nothing else; rerun_test starts it in CI. Some same-commit re-runs of a GitHub Actions test run go inside the original GitHub run and need no workflow (see rerun_test); the rest dispatch one. For a Playwright test run, the CLI in the repository must be @testdino/playwright 2.7.0 or later, 2.7.6 or later to add tags, and 2.7.8 or later for each job to run only its own failures. Full behavior is on Re-run failed tests, and the workflow inputs a repository has to declare are on Configure re-runs in GitHub Actions.
get_rerun_selection
Resolves which of a finished test run’s test cases a re-run should execute, and the command that runs them. Nothing is started.
The response carries the selected and in-scope counts, the
--test-list lines, any requested ids the test run does not have, any test case whose title cannot be carried as a line, and the CLI command. The command is null when nothing is selected.
For an e2e framework test run, the command is npx -p @testdino/e2e testdino-e2e rerun --from-run <runId> --scope <scope>, to run in the project, with --test-ids, --exclude-ids, and --rerun-tags added when testIds, excludeTestIds, or tags are passed. It is null, with a warning that says why, when the test run was uploaded by @testdino/e2e older than 1.1.0.
For any test run, the command is null, with a warning, when the test run’s details cannot be read.
The response also carries rerun_mechanism, which says what starting the re-run would do, so you can decide before you confirm:
It is absent when nothing is selected or when the answer cannot be established.
rerun_test
Re-runs the selection in CI. Costs CI minutes, so confirm must be true and you must have seen the selection first.
A same-commit re-run of a GitHub Actions test run, scoped to failed or failed-and-flaky with no testIds or excludeTestIds, re-runs the failed jobs inside the original GitHub run, so that run’s check can turn green. It takes no workflow and refuses tags. The response’s only_failed_tests says whether each job runs only its failed test cases or the whole job. Every other combination dispatches the workflow you name.
mode picks which code runs and the 2 values answer different questions: same-commit means a change in the result is the test case rather than the code, and latest answers whether a fix that landed since has worked. Because nothing in the request says which you meant, there is no default: an omitted mode is refused with MODE_REQUIRED, which carries both options and the mechanism so your assistant can put the choice to you. A same-commit re-run of a local test run that had uncommitted changes still starts, with a warning that it runs the commit as pushed, without those changes. Every refusal happens before anything is dispatched, and carries the CLI command as a fallback where one applies.
Test Controls
These tools read and change Test Controls: quarantines, critical tests, assignees, and watches. A token has the same roles as its owner on the Test Controls page (see who can use each action): a viewer can read and watch but not change anything. Test Controls settings change only in the app.quarantine_tests, release_quarantine, and set_test_critical are marked destructive, so assistants that honor the flag ask before running them.
A test is identified by its Playwright test id (testcase_id), which list_testcase returns as pw_test_id. A quarantine is identified by the quarantine_id that list_test_controls returns.
list_test_controls
Lists the tests under Test Controls in a project, as the Test Controls page shows them.
The
quarantined view also returns the project’s quarantine limit. A filter the view cannot apply is refused with INVALID_PARAM, not ignored.
Example
- “What is quarantined in this project right now?”
- “Which quarantines end in the next 3 days?”
get_test_controls
Reads 1 test’s assignee, critical flag, whether you watch it, and its active quarantine.
affectedRuns lists the test runs in the last 90 days that Test Controls changed for this test, as a total plus the 10 latest: excluded where a quarantine kept it from failing the build, and critical where it failed the build by passing only on retry while critical.
get_quarantine
Reads 1 quarantine, including a released one: reason, assignee, end date, what it covers, state, and its history of changes (events).
coveredRuns lists the test runs in the last 90 days that a quarantine of this test kept from failing the build, as a total plus the 10 latest.
quarantine_tests
Quarantines 1 to 100 tests. Until the end date, their failures stop failing the build; they still run and are reported.
Several tests are all or nothing against the quarantine limit: if they do not fit, none is quarantined. With several tests, unknown test IDs, tests already quarantined, marked critical, or not run recently, and a second browser variant of a selected test are skipped. With 1 test, an already-quarantined test returns
ALREADY_QUARANTINED, except with dry_run, which reports it as skipped. The assignee starts watching the test. A quarantine cannot be deleted, only released.
Example
- “Do a dry run of quarantining the checkout tests that failed in run #47.”
- “Quarantine this test for 7 days, assigned to me: the payment sandbox is down.”
update_quarantine
Changes an active quarantine. Only the fields you pass change.
release_quarantine
Ends a quarantine now. The test’s failures fail the build again. The quarantine moves to Released with you as the releaser, and its history is kept.
set_test_critical
Marks or unmarks a test as critical. A critical test that passes only on retry fails the build. Owners and admins only, up to 50 critical tests per project, and a quarantined test cannot be marked critical.
assign_test
Assigns a test to a project member, or unassigns it. The assignee starts watching the test.
watch_test
Watches or stops watching a test for you. Watched tests are listed by list_test_controls with view: "watched".
Test Controls errors
AI Insights
AI Insights bring TestDino’s failure analysis into the assistant: failure classification, error grouping, an AI-written run summary, and per-test-case recommendations with quick fixes. These tools require AI features to be enabled for the project (Settings → AI). When AI is off, they returnstatus: "disabled" with a message to turn it on.
AI payloads are generated on demand. A section can report not_generated, queued, processing, or failed before completed; test case fixes report in_progress before completed. Call the tool again to poll until a section reaches completed.
get_ai_insights
Returns AI analysis at 3 levels, selected by which IDs you pass.
A section that errored returns
status: "unavailable" with the upstream statusCode. A 5xx or timeout is transient, so retry once; a 4xx means the ids are wrong. A disabled status is terminal: turn AI on in Settings, since polling will not produce data.- “What should we fix first in this project?”
- “Give me the AI analysis for run #96.”
- “What is the AI-suggested fix for the failing SSO test in run #96?”
get_trace_analysis
Returns a runbook for debugging a failing test from its trace.zip with the Playwright trace CLI (npx playwright trace, Playwright 1.59+), plus a short-lived download URL for the hosted trace when you pass a testcase_id. The analysis runs on your machine: download the trace, run the CLI steps, then report the root cause and fix.
Example
- “Walk me through debugging the trace for the failing checkout test.”
- “Get the runbook for analyzing a local trace.zip.”
Test Audit
The audit flow is a read tool that fetches context and browses reports (get_audit_report) and a write tool that submits a completed report (submit_audit_report).
get_audit_report
Read-only Playwright audit reads. 3 modes via action: context fetches the server-curated audit prompt and branch signals to start an audit, list browses past reports, and get retrieves one report.
Recommended workflow
get_audit_report(action="context", branch="main")fetches the audit prompt, branch signals, and the previous audit summary for the branch.- Read only the relevant local test files, shared helpers, and
playwright.config.*. Keep raw code local. Include file paths and line numbers in findings, not large excerpts. - Build the
findingsandrecommendations, show the user the findings, and ask whether to save the audit. Submit withsubmit_audit_reportonly when they agree, or when they asked to save it. TestDino computes the score from the findings when it is saved. get_audit_report(action="list")to browse history, orget_audit_report(action="get", reportId="...")to retrieve one report.
Best practiceIf
context returns PROJECT_NOT_FOUND, auth, or access errors, resolve the correct projectId with health before continuing. Do not present a local-only fallback as a TestDino audit.- “Start a Playwright test-quality audit on main.” (→
action=context) - “List past audit reports.” / “Show audit report
rep_123.”
submit_audit_report
Final step of the audit flow. Submits a completed report with structured findings. TestDino computes the score from the findings and returns it with a per-category breakdown.
*
projectId, orgId, and the report body are required. The hosted server takes the body only as markdownReport. The local package also accepts markdownReportPath in its place.
Finding category codes: surface_level_tests, missing_validation, stability_issues, hard_to_maintain, coverage_gaps, organization_ownership, setup_configuration, duplication_overlap, other.
Example
- “Submit the audit report I completed for main.”
Test Case Management
list_manual_test_cases
Searches manual test cases within a project.
Example
get_manual_test_case
Fetches one manual test case, including steps and custom fields.
Example
create_manual_test_case
Creates a manual test case under a specific suite.
Example
update_manual_test_case
Updates only the fields you provide. All other fields remain unchanged.
A test case holds steps in 1 format. Changing
testStepsDeclarationType removes the steps in the other format, even when steps is not sent.
updates.issues links Jira or Linear issues. Pass ticket keys, for example ["PROJ-123", "ENG-9"]; each key must exist in exactly 1 connected tracker. A key that exists in both returns 400; pass that entry as { "provider": "jira" | "linear", "displayId": "KEY" } to name the tracker. With no tracker connected the call returns 409 INTEGRATION_NOT_CONNECTED. Nothing is written unless every key resolves.
updates.linkedTests is not writable here. Use link_automated_test, bulk_link_automated_tests, or unlink_automated_test to change links.
Example
list_manual_test_suites
Returns the suite hierarchy for a project.
Example
create_manual_test_suite
Creates a new suite. Use parentSuiteId to nest it under an existing suite.
Example
Automation Links
A link connects a manual test case to the automated Playwright test that covers it, so the case takes its result from CI. The Linked Tests section of a test case shows the same links in the UI. Every link call needs apwTestId and fullTitle pair. Copy both from list_automated_tests: fullTitle is a join key built by the server, and a hand-built one is rejected with Automated test not found in this project.
Linking requires the Pro plan or above and write access to the project. Unlinking works on every plan.
A typical bulk session:
list_manual_test_casesto collect each case’s internal_id.list_automated_testswithlinkStatus: "unlinked", paging withcursoruntilnextCursorisnull.bulk_link_automated_testswith the matched pairs, then checksuccesson every item in the response.get_test_case_linkson a case to confirm.
list_automated_tests
Searches the automated Playwright tests recorded for a project. Each row carries pwTestId, fullTitle, isLinked, and linkedCaseIds. The response ends with nextCursor, which is null on the last page.
get_test_case_links
Lists the automated tests linked to 1 manual test case, with each link’s successRate, lastExecution, and platforms. Use it to find the linkId that unlink_automated_test needs. get_manual_test_case returns the same links as linkedTests without the metrics.
link_automated_test
Links 1 automated test to 1 manual test case and sets the case’s automation status to Automated. A case holds at most 50 links.
The call is rejected with
This automated test is already linked to this test case when the pair exists, and with Maximum 50 linked tests per test case at the cap.
unlink_automated_test
Removes 1 link by its linkId. When the last link is removed, the case’s automation status returns to Manual.
bulk_link_automated_tests
Links up to 500 manual test case and automated test pairs in 1 call. The response holds 1 result per pair with manualTestCaseId, fullTitle, and success, plus link when the pair linked or error when it did not. A failed pair does not stop the rest, so check success on every item.
manualTestCaseId is the case’s internal _id (e.g., tcm_tc_...) as returned by list_manual_test_cases, not the TC-123 ID.
Releases
Releases track sprints and versions for a project and appear as Milestones in the TestDino app; the tool and parameter names keeprelease. They nest up to 3 levels deep. Reference releases using counter-style IDs like MS-12. Error messages call them milestones, for example Milestone not found.
list_releases
Returns releases for a project with filtering by type, status, completion, and name.
get_release
Returns full details for one release: dates, status, linked issues, parent/root release, and rolled-up progress stats across all runs in the release and its descendants.
create_release
Creates a release or milestone. Use parentReleaseId to nest under an existing release (max 3 levels deep).
update_release
Updates only the fields you provide inside the updates object. All other fields remain unchanged.
Manual Test Runs
Manual test runs track the execution of test cases by a team. Each run belongs to a project and attaches optionally to a release. Reference runs using counter-style IDs likeRUN-12.
list_manual_runs
Returns manual test runs for a project with filtering by status, state, environment, release, and tags.
get_manual_run
Returns full details for one manual test run: name, status, state, environment, linked release, test stats (total/passed/failed/blocked/untested), contributors, attachments, and linked issues.
create_manual_run
Creates a manual test run. By default, all test cases in the project are included. You can optionally provide testCaseIds or suiteIds to limit the run to a specific subset.
update_manual_run
Updates only the fields you provide inside the updates object.
list_run_test_cases
Returns per-case execution records inside a manual run. Each record shows the test case identity (caseKey like TC-156), current assignee, and current result.
Call this before update_run_test_case to get the rtcRef for each case you want to update.
update_run_test_case
Updates a test case record within a manual run. You can set the outcome, assign it to a user, or include step results to capture a complete result entry.
NoteDo not combine
assigneeUserId with detailed result fields (comment, linkedIssues, stepResults, configuration) in a single call. The server rejects this. Make 2 separate calls: one to assign, one to record the detailed result.Exploratory Sessions
Exploratory sessions track unscripted testing against a mission or charter. Each session belongs to a project and attaches optionally to a release. Reference sessions using counter-style IDs likeSES-12.
list_sessions
Returns exploratory sessions for a project with filtering by status, state, session type, assignee, release, and tags.
get_session
Returns full details for one exploratory session: name, mission, status, assignee, linked release, attachments, linked issues, and findings.
create_session
Creates an exploratory session. Use mission to define the testing charter and releaseId to attach the session to a release.
NoteFindings are not available via MCP. Add findings in the TestDino UI after creating the session.
update_session
Updates only the fields you provide inside the updates object.
Integrations
Connect issue trackers and file issues from TestDino entities. Supported providers:jira, linear, asana, monday, and github. Issues can be created in all of them except github, and read from jira, linear, and asana.
get_integration_status
Checks whether a provider is connected for a project, and optionally returns the projects, issue types, and fields needed to create an issue.
Example
- “Is Jira connected for this project?”
- “Get Jira create options for project key TRX and Bug issue type.”
connect_integration
Starts an OAuth connection for a provider. Returns already_connected, or a connect URL to open.
NoteShow the returned connect URL to the user. Do not open it programmatically.
- “Connect Linear for this project.”
create_external_issue
Files a provider issue from a TestDino entity such as a test case, run, or manual case.
source.type values: test_run, test_suite, test_case, manual_test_case, manual_test_suite, release, manual_run, manual_run_test_case, session.
Example
- “File a Jira bug for the failing test case
a1b2c3in run #47 and link it back.” - “Preview the Linear issue you’d create for manual case TC-142.”
get_external_issue
Fetches one or more previously linked external issues.
Example
- “Is Jira issue TD-17 still open?”
- “Check the status of TD-17, TD-18 and TD-19.”
Prompts
Prompts are guided workflows the MCP server exposes alongside its tools. Clients that support MCP prompts list them as slash commands, so you pick the workflow from a menu instead of describing it.optimize_swarm reads the per-machine timings of a run distributed with swarm mode and explains why it took as long as it did, how many CI minutes sat idle, and the 1 change that would make it faster. It tells uneven packing across machines apart from a single long spec file, which more machines cannot speed up. Pass compare_to_run_id with testrun_id to check whether a change, such as splitting a long spec file or changing the machine count, actually shortened the run.
Each prompt carries scope only, never test run data, so the assistant reads current state rather than a snapshot. fix_run groups a test run’s failures by shared cause and orders them largest group first, because one fix there often closes many test cases at once. fix_case and fix_flake both close at verify_fix, so the assistant confirms the change against TestDino instead of judging its own work.
If you do not name a test case, fix_case lists the failing test cases first and asks which one to work on.
Prompt support varies by client. When your assistant does not list prompts, ask for the same workflow in your own words and name the test run or test case. The Debug with AI button copies an instruction that works either way.
Related
MCP Overview
What the MCP server does and when to use it
Remote MCP
Connect a hosted client with your PAT
Local MCP
Run the server on your own machine
MCP Troubleshooting
Fix connection, auth, and tool call errors