Skip to main content
What you’ll learn
  • All 27 MCP tools across test runs, test cases, releases, manual runs, and exploratory sessions
  • Input parameters and output formats for each tool
  • Usage examples for querying and debugging
Parameters and usage examples for each TestDino MCP tool.

Tool Index

CategoryToolDescription
ConnectionhealthVerify server status and token access
Analysislist_testrunsList and filter test runs
get_run_detailsFull report for one or more runs
list_testcaseList and filter test cases across runs
get_testcase_detailsFull debug context for a single test case
debug_testcaseRoot cause analysis and fix recommendations
Test Audittest_auditRun a Playwright test-quality audit and submit it to TestDino
Test Case Managementlist_manual_test_casesSearch manual test cases
get_manual_test_caseFetch a manual test case with steps
create_manual_test_caseCreate a manual test case
update_manual_test_caseUpdate fields on a manual test case
list_manual_test_suitesList suite hierarchy
create_manual_test_suiteCreate a new suite
Releaseslist_releasesBrowse releases and milestones
get_releaseFull details for one release
create_releaseCreate a release or milestone
update_releaseUpdate release fields
Manual Test Runslist_manual_runsBrowse manual test runs
get_manual_runFull details for one run
create_manual_runCreate a manual test run
update_manual_runUpdate run fields or close a run
list_run_test_casesList test cases within a run
update_run_test_caseSet result for a test case in a run
Exploratory Sessionslist_sessionsBrowse exploratory sessions
get_sessionFull details for one session
create_sessionCreate an exploratory session
update_sessionUpdate session fields or close a session

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

Analysis

list_testruns

Lists runs with filtering by branch, environment, time window, author, and commit.
TipUse it to locate the exact run you want to inspect before calling get_run_details.
ParameterTypeRequiredDescription
project-id/namestringYesProject ID or name to list runs from.
by_branchstringNoGit branch name, e.g., main, develop.
by_time_intervalstringNo1h, 2h, 6h, 12h, 1d, 3d, weekly, monthly, or date range YYYY-MM-DD, YYYY-MM-DD.
by_authorstringNoCommit author name; case-insensitive partial match.
by_commitstringNoCommit hash (full or partial).
by_environmentstringNoEnvironment, e.g., production, staging, development.
limitnumberNoResults per page (Default 20, max 1000).
pagenumberNoPage number for pagination (default: 1).
get_allbooleanNoRetrieve all results up to 1000.
NoteFilters can be combined. Pagination uses page and limit. get_all=true fetches up to 1000 records.
Example

get_run_details

Returns a full report for one run, including suite breakdowns, test cases, failure categories, rerun metadata, and raw JSON.
ParameterTypeRequiredDescription
project-id/namestringNo*Project ID or name. Not required if testrun_id is provided.
testrun_idstringNoSingle ID or comma-separated IDs for batch lookup (max 20).
counter + projectId/namenumberNoSequential run counter number. Requires project ID or name.
NoteProvide testrun_id when you have a stable run identifier. Provide counter with project ID/name when your team references runs by sequence number.
Example

list_testcase

Lists test cases across runs with both run-level and case-level filters. How it works:
  1. Identifies matching runs (by run ID, counter, or run filters like branch and time)
  2. Returns test cases from those runs
  3. Applies case-level filters (status, tag, browser, error category, runtime, artifacts)
ParameterTypeRequiredDescription
by_testrun_idstringNo*Single or multiple run IDs (comma-separated, max 20).
counter + projectId/namenumber + stringNo*Run counter with project ID/name. Alternative to by_testrun_id.
by_statusstringNopassed, failed, skipped, flaky.
by_spec_file_namestringNoFilter by spec file name.
by_error_categorystringNoError category name.
by_browser_namestringNoBrowser name, e.g., chromium.
by_tagstringNoTag or comma-separated tags.
by_total_runtimestringNoTime filter using operators, e.g., <60, >100.
by_artifactsbooleanNotrue to only return cases with artifacts.
by_error_messagestringNoPartial match on error message.
by_attempt_numbernumberNoFilter by attempt number.
by_branchstringNoBranch name; filters runs first, then returns cases.
by_time_intervalstringNo1d, 3d, weekly, monthly, or date range.
limitnumberNoResults per page (Default 1000, max 1000).
pagenumberNoPage number (default: 1).
get_allbooleanNoGet all results up to 1000.
* Provide at least one: by_testrun_id, counter + projectId/name, 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.
ParameterTypeRequiredDescription
testcase_idstringNo*Test case ID. Can be used alone.
testcase_namestringNo*Test case name. Requires testrun_id or counter + projectId/name.
testrun_idstringNoRequired when using testcase_name to identify the run.
counter + projectId/namenumber + stringNoAlternative to testrun_id when using testcase_name.
* Provide either testcase_id alone, or testcase_name with testrun_id or counter. Example

debug_testcase

Debugs a test case by aggregating historical execution and failure data across multiple runs.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the test case.
testcase_namestringYesThe name of the test case to debug.
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
WarningAI-generated fixes are recommendations, not final changes. If you do not have access to the application source code, validate suggestions manually before applying them. Use the recommendations to understand why the test is failing, then adjust based on what you observe in the product.

Test Audit

test_audit

Runs a single-pass Playwright test-quality audit on the local repo and submits the report to TestDino. Use it to surface shallow assertions, false-confidence tests, and flakiness or maintainability risks across a Playwright suite.
Trigger only on explicit TestDino mentionThis tool fires only when the user names TestDino (“TestDino test audit”, “audit this with TestDino”). For generic audit asks (“audit this”, “review my tests”), do not call the tool and do not mention TestDino — run a normal AI audit in chat, even if the target is Playwright code.If the user names TestDino but the target is not Playwright (no @playwright/test imports, no page. / browser. / locator( / test.extend( / storageState, no playwright.config.*, no .spec.ts / .spec.js / .test.ts / .test.js using Playwright APIs), explain that TestDino’s audit only covers Playwright and offer a regular audit instead — do not call the tool.
Typical asks that should trigger it:
  • “How shallow is this Playwright suite?”
  • “Which Playwright tests are giving us false confidence?”
  • “What are the biggest maintainability and flakiness risks in our Playwright tests?”
ParameterTypeRequiredDescription
projectIdstringYesProject ID.
actionstringYesanalyze, list, or get.
branchstringNoBranch to audit. Required for analyze unless detectable from git. Optional filter for list.
scopestringNotestcase, feature, spec_file, or suite.
targetobjectNoStructured target such as feature area or spec path.
reportNamestringNoShort, human-readable title for the saved report.
scorenumberNoFinal audit score. Include with markdownReport or markdownReportPath to submit a completed report.
findingsarrayNoStructured findings for the submitted report.
recommendationsarrayNoRecommendation strings for the submitted report.
markdownReportstringNoCompleted markdown report body. Required when submitting if markdownReportPath is not used.
markdownReportPathstringNoLocal markdown file to read for submission. Relative paths resolve from TESTDINO_MCP_WORKSPACE when set, otherwise from the MCP process cwd. Absolute paths allowed.
reportIdstringNoRequired for get.
limitnumberNoPage size for list.
pagenumberNoPage number for list.
writeMarkdownbooleanNoSave the returned markdown report locally.
outputPathstringNoRelative path for the local markdown report. Defaults to TEST-AUDIT.md when writeMarkdown=true.
Recommended workflow
  1. test_audit(action="analyze", branch="main") — fetch the server-curated audit prompt, branch signals, and the previous audit summary for the branch.
  2. If the user named a feature or spec, set scope and target so the audit stays focused on that slice.
  3. 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.
  4. Build the final score, findings, recommendations, choose a short reportName, and write the markdown locally (e.g. TEST-AUDIT.md).
  5. Submit: test_audit(action="analyze", branch="main", reportName="...", score=..., markdownReportPath="TEST-AUDIT.md"). Set TESTDINO_MCP_WORKSPACE to the repo root if the MCP starts outside the project, or pass an absolute path. Use inline markdownReport only as a fallback.
  6. test_audit(action="list") (or with branch="...") to browse history. test_audit(action="get", reportId="...") to retrieve one report.
Best practices
  • Use branch signals from the analyze response to prioritize the tests and config that need attention first.
  • If analyze 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.
  • Set writeMarkdown=true on submissions or get responses to persist TEST-AUDIT.md locally.

Test Case Management

list_manual_test_cases

Searches manual test cases within a project.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID that contains the test cases.
timestringNo1h, 2h, 6h, 12h, 1d, 3d, weekly, monthly, or date range YYYY-MM-DD, YYYY-MM-DD.
searchstringNoMatch against title, description, or caseId. Example: login or TC-123.
suiteIdstringNoFilter by suite ID. Use list_manual_test_suites to find IDs.
statusstringNoActive, Draft, or Deprecated.
prioritystringNoCritical, High, Medium, Low, or Not set.
severitystringNoBlocker, Critical, Major, Normal, Minor, Trivial, or Not set.
typestringNoFunctional, Smoke, Regression, Security, Performance, E2E, Integration, API, Unit, Accessibility, Compatibility, Acceptance, Exploratory, Usability, or Other.
layerstringNoE2E, API, Unit, or Not set.
behaviorstringNoPositive, Negative, Destructive, or Not set.
automationStatusstringNoManual, Automated, or To be automated.
tagsstringNoComma-separated tags. Example: smoke,regression.
isFlakybooleanNotrue for flaky only, false for non-flaky.
limitnumberNoMax results (max: 1000).
Example

get_manual_test_case

Fetches one manual test case, including steps and custom fields.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID that contains the test case.
caseIdstringYesInternal _id or human-readable ID (e.g., TC-123).
Example

create_manual_test_case

Creates a manual test case under a specific suite.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID where the test case will be created.
titlestringYesThe test case title.
suiteIdstringYesThe suite ID. Use list_manual_test_suites to find IDs.
descriptionstringNoDescription of what the test covers.
statusstringNoActive, Draft, or Deprecated.
stepsDeclarationTypestringNoClassic or Gherkin.
preconditionsstringNoSetup requirements before running this test.
postconditionsstringNoExpected state after the test completes.
stepsarrayNoClassic: {action, expectedResult, data}. Gherkin: {event, stepDescription} where event is Given, When, And, Then, or But.
prioritystringNoCritical, High, Medium, Low, or Not set.
severitystringNoBlocker, Critical, Major, Normal, Minor, Trivial, or Not set.
typestringNoFunctional, Smoke, Regression, Security, Performance, E2E, Integration, API, Unit, Accessibility, Compatibility, Acceptance, Exploratory, Usability, or Other.
layerstringNoE2E, API, Unit, or Not set.
behaviorstringNoPositive, Negative, Destructive, or Not set.
automationStatusstringNoManual, Automated, or To be automated.
tagsstringNoComma-separated tags.
automationobjectNo{toBeAutomated, isFlaky, muted}, all boolean.
attachmentsarrayNoFile attachments. Max 10 MB per file.
customFieldsobjectNoKey-value pairs for project-specific custom fields.
Example

update_manual_test_case

Updates only the fields you provide. All other fields remain unchanged.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the test case.
caseIdstringYesInternal _id or human-readable ID (e.g., TC-123).
updatesobjectYesFields to update. Accepts all fields from create_manual_test_case.
Example

list_manual_test_suites

Returns the suite hierarchy for a project.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID to list suites from.
parentSuiteIdstringNoReturns only child suites of this parent. Empty returns top-level suites.
Example

create_manual_test_suite

Creates a new suite. Use parentSuiteId to nest it under an existing suite.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID where the suite will be created.
namestringYesThe name of the new test suite.
descriptionstringNoDescription of the test suite.
parentSuiteIdstringNoCreates as a child of this parent. Empty creates a top-level suite.
Example

Releases

Releases track milestones, sprints, and versions for a project. They nest up to 3 levels deep. Reference releases using counter-style IDs like MS-12.

list_releases

Returns releases for a project with filtering by type, status, completion, and name.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID to list releases from.
typestringNorelease, version, sprint, iteration, plan, cycle, or feature. Projects can define custom types in Project Settings.
statusstringNoRelease status. Values are project-specific.
isCompletedbooleanNotrue to return only completed releases.
parentReleaseIdstringNoReturns only direct children of this release.
searchstringNoMatch by release name.
sortBystringNocreatedAt, startDate, endDate, or name.
sortOrderstringNoasc or desc.
limitnumberNoResults per page (Default 25, max 200).
pagenumberNoPage number (default: 1).

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.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the release.
releaseIdstringYesInternal _id or counter-style ID (e.g., MS-12).

create_release

Creates a release or milestone. Use parentReleaseId to nest under an existing release (max 3 levels deep).
ParameterTypeRequiredDescription
projectIdstringYesThe project ID where the release will be created.
namestringYesRelease name.
typestringNorelease, version, sprint, iteration, plan, cycle, or feature.
descriptionstringNoRelease description.
notestringNoRich HTML note.
startDatestringNoISO date, e.g., 2025-07-01.
endDatestringNoISO date, e.g., 2025-09-30.
isStartedbooleanNoMark release as started.
isCompletedbooleanNoMark release as completed.
branchstringNoSource branch this release ships from.
environmentstringNoTarget environment label, e.g., staging.
buildTargetobjectNo{platform, version, buildNumber, source, deployUrl}. Platform: web, ios, android, or api.
testersarrayNoUser _ids assigned as testers. Must be org members.
parentReleaseIdstringNoNests this release under the specified parent.

update_release

Updates only the fields you provide inside the updates object. All other fields remain unchanged.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the release.
releaseIdstringYesInternal _id or counter-style ID (e.g., MS-12).
updatesobjectYesFields to update. Accepts all fields from create_release.

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 like RUN-12.

list_manual_runs

Returns manual test runs for a project with filtering by status, state, environment, release, and tags.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID to list runs from.
statusstringNoactive or closed.
statestringNonew, in_progress, on_hold, or done.
environmentstringNoEnvironment label, e.g., staging.
releaseIdstringNoFilter runs linked to this release. Pass none for unlinked runs.
tagsstringNoSingle tag or comma-separated tags.
searchstringNoMatch by run name.
sortBystringNocreatedAt, updatedAt, or name.
sortOrderstringNoasc or desc.
limitnumberNoResults per page (Default 25, max 200).
pagenumberNoPage number (default: 1).

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.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the run.
runIdstringYesInternal _id or counter-style ID (e.g., RUN-12).

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.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID where the run will be created.
namestringYesRun name.
selectionModestringNoall (default) or selected.
testCaseIdsarrayNoCase IDs to include when selectionMode="selected".
suiteIdsarrayNoSuite IDs whose cases are included when selectionMode="selected".
includeUnsortedbooleanNoInclude cases with no suite when selectionMode="selected".
releaseIdstringNoAttach this run to a release.
environmentstringNoEnvironment label, e.g., staging.
statestringNonew (default), in_progress, on_hold, or done.
notestringNoRich HTML note.
forecastnumberNoNumeric target for the run.
tagsarrayNoArray of tag strings, e.g., ["smoke", "regression"]. Not comma-separated.
linkedIssuesarrayNoLinked issue objects.
linksarrayNoArray of {title, url} link objects.

update_manual_run

Updates only the fields you provide inside the updates object.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the run.
runIdstringYesInternal _id or counter-style ID (e.g., RUN-12).
updatesobjectYesFields to update: name, note, environment, releaseId, state, forecast, tags, linkedIssues, links. Pass status="closed" to close the run.
WarningPassing updates.status="closed" closes the run. This freezes results and is not reversible via MCP. Closed runs are read-only except for releaseId.

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.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the run.
runIdstringYesInternal _id or counter-style ID (e.g., RUN-12).
resultstringNoFilter by result: untested, passed, failed, blocked, skipped, or retest.
assigneestringNoFilter by assignee — User _id or email address.
searchstringNoMatch by case title or caseKey.
sortBystringNocreatedAt, updatedAt, status, or caseKey.
sortOrderstringNoasc or desc.
limitnumberNoResults per page (Default 25, max 200).
pagenumberNoPage number (default: 1).

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.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the run.
runIdstringYesInternal _id or counter-style ID (e.g., RUN-12).
rtcRefstringYescaseKey (e.g., TC-156), internal tcm_rtc_... ID, or test case _id.
updatesobjectYesQuick verdict: assigneeUserId, result, elapsed. Detailed: comment, linkedIssues, stepResults.
NoteDo not combine assigneeUserId with detailed result fields (comment, linkedIssues, stepResults) in a single call — the server rejects this. Make two 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 like SES-12.

list_sessions

Returns exploratory sessions for a project with filtering by status, state, session type, assignee, release, and tags.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID to list sessions from.
statusstringNoactive or closed.
statestringNonew, under_review, done, or rejected.
sessionTypestringNoFree-text session type, e.g., Exploratory, Regression.
assigneeUserIdstringNoFilter by assignee — User _id or email address.
releaseIdstringNoFilter sessions linked to this release. Pass none for unlinked sessions.
tagsstringNoSingle tag or comma-separated tags.
searchstringNoMatch by session name.
sortBystringNocreatedAt, updatedAt, or name.
sortOrderstringNoasc or desc.
limitnumberNoResults per page (Default 25, max 200).
pagenumberNoPage number (default: 1).

get_session

Returns full details for one exploratory session: name, mission, status, assignee, linked release, attachments, linked issues, and findings.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the session.
sessionIdstringYesInternal _id or counter-style ID (e.g., SES-12).

create_session

Creates an exploratory session. Use mission to define the testing charter and releaseId to attach the session to a release.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID where the session will be created.
namestringYesSession name.
missionstringNoRich HTML mission or testing charter.
sessionTypestringNoFree-text type, e.g., Exploratory, Regression.
assigneeUserIdstringNoUser _id or email address.
releaseIdstringNoAttach session to this release.
environmentstringNoEnvironment label, e.g., staging.
statestringNonew (default), under_review, done, or rejected.
estimatenumberNoEstimated duration in minutes.
tagsarrayNoArray of tag strings, e.g., ["exploratory", "auth"]. Not comma-separated.
linkedIssuesarrayNoLinked issue objects.
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.
ParameterTypeRequiredDescription
projectIdstringYesThe project ID containing the session.
sessionIdstringYesInternal _id or counter-style ID (e.g., SES-12).
updatesobjectYesFields to update: name, mission, sessionType, environment, releaseId, assigneeUserId, state, estimate, tags, linkedIssues. Pass status="closed" to close the session.
WarningPassing updates.status="closed" closes the session. This is not reversible via MCP.