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
Tool Index
| Category | Tool | Description |
|---|---|---|
| Connection | health | Verify server status and token access |
| Analysis | list_testruns | List and filter test runs |
get_run_details | Full report for one or more runs | |
list_testcase | List and filter test cases across runs | |
get_testcase_details | Full debug context for a single test case | |
debug_testcase | Root cause analysis and fix recommendations | |
| Test Audit | test_audit | Run a Playwright test-quality audit and submit it to TestDino |
| Test Case Management | list_manual_test_cases | Search manual test cases |
get_manual_test_case | Fetch a manual test case with steps | |
create_manual_test_case | Create a manual test case | |
update_manual_test_case | Update fields on a manual test case | |
list_manual_test_suites | List suite hierarchy | |
create_manual_test_suite | Create a new suite | |
| Releases | list_releases | Browse releases and milestones |
get_release | Full details for one release | |
create_release | Create a release or milestone | |
update_release | Update release fields | |
| Manual Test Runs | list_manual_runs | Browse manual test runs |
get_manual_run | Full details for one run | |
create_manual_run | Create a manual test run | |
update_manual_run | Update run fields or close a run | |
list_run_test_cases | List test cases within a run | |
update_run_test_case | Set result for a test case in a run | |
| Exploratory Sessions | list_sessions | Browse exploratory sessions |
get_session | Full details for one session | |
create_session | Create an exploratory session | |
update_session | Update 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
project-id/name | string | Yes | Project ID or name to list runs from. |
by_branch | string | No | Git branch name, e.g., main, develop. |
by_time_interval | string | No | 1h, 2h, 6h, 12h, 1d, 3d, weekly, monthly, or date range YYYY-MM-DD, YYYY-MM-DD. |
by_author | string | No | Commit author name; case-insensitive partial match. |
by_commit | string | No | Commit hash (full or partial). |
by_environment | string | No | Environment, e.g., production, staging, development. |
limit | number | No | Results per page (Default 20, max 1000). |
page | number | No | Page number for pagination (default: 1). |
get_all | boolean | No | Retrieve all results up to 1000. |
NoteFilters can be combined. Pagination uses
page and limit. get_all=true fetches up to 1000 records.get_run_details
Returns a full report for one run, including suite breakdowns, test cases, failure categories, rerun metadata, and raw JSON.
| Parameter | Type | Required | Description |
|---|---|---|---|
project-id/name | string | No* | Project ID or name. Not required if testrun_id is provided. |
testrun_id | string | No | Single ID or comma-separated IDs for batch lookup (max 20). |
counter + projectId/name | number | No | Sequential 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.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)
| Parameter | Type | Required | Description |
|---|---|---|---|
by_testrun_id | string | No* | Single or multiple run IDs (comma-separated, max 20). |
counter + projectId/name | number + string | No* | Run counter with project ID/name. Alternative to by_testrun_id. |
by_status | string | No | passed, failed, skipped, flaky. |
by_spec_file_name | string | No | Filter by spec file name. |
by_error_category | string | No | Error category name. |
by_browser_name | string | No | Browser name, e.g., chromium. |
by_tag | string | No | Tag or comma-separated tags. |
by_total_runtime | string | No | Time filter using operators, e.g., <60, >100. |
by_artifacts | boolean | No | true to only return cases with artifacts. |
by_error_message | string | No | Partial match on error message. |
by_attempt_number | number | No | Filter by attempt number. |
by_branch | string | No | Branch name; filters runs first, then returns cases. |
by_time_interval | string | No | 1d, 3d, weekly, monthly, or date range. |
limit | number | No | Results per page (Default 1000, max 1000). |
page | number | No | Page number (default: 1). |
get_all | boolean | No | Get all results up to 1000. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
testcase_id | string | No* | Test case ID. Can be used alone. |
testcase_name | string | No* | Test case name. Requires testrun_id or counter + projectId/name. |
testrun_id | string | No | Required when using testcase_name to identify the run. |
counter + projectId/name | number + string | No | Alternative to testrun_id when using testcase_name. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the test case. |
testcase_name | string | Yes | The name of the test case to debug. |
- 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
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.
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?”
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | Project ID. |
action | string | Yes | analyze, list, or get. |
branch | string | No | Branch to audit. Required for analyze unless detectable from git. Optional filter for list. |
scope | string | No | testcase, feature, spec_file, or suite. |
target | object | No | Structured target such as feature area or spec path. |
reportName | string | No | Short, human-readable title for the saved report. |
score | number | No | Final audit score. Include with markdownReport or markdownReportPath to submit a completed report. |
findings | array | No | Structured findings for the submitted report. |
recommendations | array | No | Recommendation strings for the submitted report. |
markdownReport | string | No | Completed markdown report body. Required when submitting if markdownReportPath is not used. |
markdownReportPath | string | No | Local markdown file to read for submission. Relative paths resolve from TESTDINO_MCP_WORKSPACE when set, otherwise from the MCP process cwd. Absolute paths allowed. |
reportId | string | No | Required for get. |
limit | number | No | Page size for list. |
page | number | No | Page number for list. |
writeMarkdown | boolean | No | Save the returned markdown report locally. |
outputPath | string | No | Relative path for the local markdown report. Defaults to TEST-AUDIT.md when writeMarkdown=true. |
test_audit(action="analyze", branch="main")— fetch the server-curated audit prompt, branch signals, and the previous audit summary for the branch.- If the user named a feature or spec, set
scopeandtargetso the audit stays focused on that slice. - 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 final
score,findings,recommendations, choose a shortreportName, and write the markdown locally (e.g.TEST-AUDIT.md). - Submit:
test_audit(action="analyze", branch="main", reportName="...", score=..., markdownReportPath="TEST-AUDIT.md"). SetTESTDINO_MCP_WORKSPACEto the repo root if the MCP starts outside the project, or pass an absolute path. Use inlinemarkdownReportonly as a fallback. test_audit(action="list")(or withbranch="...") to browse history.test_audit(action="get", reportId="...")to retrieve one report.
Best practices
- Use branch signals from the
analyzeresponse to prioritize the tests and config that need attention first. - If
analyzereturnsPROJECT_NOT_FOUND, auth, or access errors, resolve the correctprojectIdwithhealth()before continuing. Do not present a local-only fallback as a TestDino audit. - Set
writeMarkdown=trueon submissions orgetresponses to persistTEST-AUDIT.mdlocally.
Test Case Management
list_manual_test_cases
Searches manual test cases within a project.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID that contains the test cases. |
time | string | No | 1h, 2h, 6h, 12h, 1d, 3d, weekly, monthly, or date range YYYY-MM-DD, YYYY-MM-DD. |
search | string | No | Match against title, description, or caseId. Example: login or TC-123. |
suiteId | string | No | Filter by suite ID. Use list_manual_test_suites to find IDs. |
status | string | No | Active, Draft, or Deprecated. |
priority | string | No | Critical, High, Medium, Low, or Not set. |
severity | string | No | Blocker, Critical, Major, Normal, Minor, Trivial, or Not set. |
type | string | No | Functional, Smoke, Regression, Security, Performance, E2E, Integration, API, Unit, Accessibility, Compatibility, Acceptance, Exploratory, Usability, or Other. |
layer | string | No | E2E, API, Unit, or Not set. |
behavior | string | No | Positive, Negative, Destructive, or Not set. |
automationStatus | string | No | Manual, Automated, or To be automated. |
tags | string | No | Comma-separated tags. Example: smoke,regression. |
isFlaky | boolean | No | true for flaky only, false for non-flaky. |
limit | number | No | Max results (max: 1000). |
get_manual_test_case
Fetches one manual test case, including steps and custom fields.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID that contains the test case. |
caseId | string | Yes | Internal _id or human-readable ID (e.g., TC-123). |
create_manual_test_case
Creates a manual test case under a specific suite.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID where the test case will be created. |
title | string | Yes | The test case title. |
suiteId | string | Yes | The suite ID. Use list_manual_test_suites to find IDs. |
description | string | No | Description of what the test covers. |
status | string | No | Active, Draft, or Deprecated. |
stepsDeclarationType | string | No | Classic or Gherkin. |
preconditions | string | No | Setup requirements before running this test. |
postconditions | string | No | Expected state after the test completes. |
steps | array | No | Classic: {action, expectedResult, data}. Gherkin: {event, stepDescription} where event is Given, When, And, Then, or But. |
priority | string | No | Critical, High, Medium, Low, or Not set. |
severity | string | No | Blocker, Critical, Major, Normal, Minor, Trivial, or Not set. |
type | string | No | Functional, Smoke, Regression, Security, Performance, E2E, Integration, API, Unit, Accessibility, Compatibility, Acceptance, Exploratory, Usability, or Other. |
layer | string | No | E2E, API, Unit, or Not set. |
behavior | string | No | Positive, Negative, Destructive, or Not set. |
automationStatus | string | No | Manual, Automated, or To be automated. |
tags | string | No | Comma-separated tags. |
automation | object | No | {toBeAutomated, isFlaky, muted}, all boolean. |
attachments | array | No | File attachments. Max 10 MB per file. |
customFields | object | No | Key-value pairs for project-specific custom fields. |
update_manual_test_case
Updates only the fields you provide. All other fields remain unchanged.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the test case. |
caseId | string | Yes | Internal _id or human-readable ID (e.g., TC-123). |
updates | object | Yes | Fields to update. Accepts all fields from create_manual_test_case. |
list_manual_test_suites
Returns the suite hierarchy for a project.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID to list suites from. |
parentSuiteId | string | No | Returns only child suites of this parent. Empty returns top-level suites. |
create_manual_test_suite
Creates a new suite. Use parentSuiteId to nest it under an existing suite.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID where the suite will be created. |
name | string | Yes | The name of the new test suite. |
description | string | No | Description of the test suite. |
parentSuiteId | string | No | Creates as a child of this parent. Empty creates a top-level suite. |
Releases
Releases track milestones, sprints, and versions for a project. They nest up to 3 levels deep. Reference releases using counter-style IDs likeMS-12.
list_releases
Returns releases for a project with filtering by type, status, completion, and name.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID to list releases from. |
type | string | No | release, version, sprint, iteration, plan, cycle, or feature. Projects can define custom types in Project Settings. |
status | string | No | Release status. Values are project-specific. |
isCompleted | boolean | No | true to return only completed releases. |
parentReleaseId | string | No | Returns only direct children of this release. |
search | string | No | Match by release name. |
sortBy | string | No | createdAt, startDate, endDate, or name. |
sortOrder | string | No | asc or desc. |
limit | number | No | Results per page (Default 25, max 200). |
page | number | No | Page 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the release. |
releaseId | string | Yes | Internal _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).
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID where the release will be created. |
name | string | Yes | Release name. |
type | string | No | release, version, sprint, iteration, plan, cycle, or feature. |
description | string | No | Release description. |
note | string | No | Rich HTML note. |
startDate | string | No | ISO date, e.g., 2025-07-01. |
endDate | string | No | ISO date, e.g., 2025-09-30. |
isStarted | boolean | No | Mark release as started. |
isCompleted | boolean | No | Mark release as completed. |
branch | string | No | Source branch this release ships from. |
environment | string | No | Target environment label, e.g., staging. |
buildTarget | object | No | {platform, version, buildNumber, source, deployUrl}. Platform: web, ios, android, or api. |
testers | array | No | User _ids assigned as testers. Must be org members. |
parentReleaseId | string | No | Nests this release under the specified parent. |
update_release
Updates only the fields you provide inside the updates object. All other fields remain unchanged.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the release. |
releaseId | string | Yes | Internal _id or counter-style ID (e.g., MS-12). |
updates | object | Yes | Fields 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 likeRUN-12.
list_manual_runs
Returns manual test runs for a project with filtering by status, state, environment, release, and tags.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID to list runs from. |
status | string | No | active or closed. |
state | string | No | new, in_progress, on_hold, or done. |
environment | string | No | Environment label, e.g., staging. |
releaseId | string | No | Filter runs linked to this release. Pass none for unlinked runs. |
tags | string | No | Single tag or comma-separated tags. |
search | string | No | Match by run name. |
sortBy | string | No | createdAt, updatedAt, or name. |
sortOrder | string | No | asc or desc. |
limit | number | No | Results per page (Default 25, max 200). |
page | number | No | Page 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the run. |
runId | string | Yes | Internal _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.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID where the run will be created. |
name | string | Yes | Run name. |
selectionMode | string | No | all (default) or selected. |
testCaseIds | array | No | Case IDs to include when selectionMode="selected". |
suiteIds | array | No | Suite IDs whose cases are included when selectionMode="selected". |
includeUnsorted | boolean | No | Include cases with no suite when selectionMode="selected". |
releaseId | string | No | Attach this run to a release. |
environment | string | No | Environment label, e.g., staging. |
state | string | No | new (default), in_progress, on_hold, or done. |
note | string | No | Rich HTML note. |
forecast | number | No | Numeric target for the run. |
tags | array | No | Array of tag strings, e.g., ["smoke", "regression"]. Not comma-separated. |
linkedIssues | array | No | Linked issue objects. |
links | array | No | Array of {title, url} link objects. |
update_manual_run
Updates only the fields you provide inside the updates object.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the run. |
runId | string | Yes | Internal _id or counter-style ID (e.g., RUN-12). |
updates | object | Yes | Fields to update: name, note, environment, releaseId, state, forecast, tags, linkedIssues, links. Pass status="closed" to close the run. |
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the run. |
runId | string | Yes | Internal _id or counter-style ID (e.g., RUN-12). |
result | string | No | Filter by result: untested, passed, failed, blocked, skipped, or retest. |
assignee | string | No | Filter by assignee — User _id or email address. |
search | string | No | Match by case title or caseKey. |
sortBy | string | No | createdAt, updatedAt, status, or caseKey. |
sortOrder | string | No | asc or desc. |
limit | number | No | Results per page (Default 25, max 200). |
page | number | No | Page 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the run. |
runId | string | Yes | Internal _id or counter-style ID (e.g., RUN-12). |
rtcRef | string | Yes | caseKey (e.g., TC-156), internal tcm_rtc_... ID, or test case _id. |
updates | object | Yes | Quick 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 likeSES-12.
list_sessions
Returns exploratory sessions for a project with filtering by status, state, session type, assignee, release, and tags.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID to list sessions from. |
status | string | No | active or closed. |
state | string | No | new, under_review, done, or rejected. |
sessionType | string | No | Free-text session type, e.g., Exploratory, Regression. |
assigneeUserId | string | No | Filter by assignee — User _id or email address. |
releaseId | string | No | Filter sessions linked to this release. Pass none for unlinked sessions. |
tags | string | No | Single tag or comma-separated tags. |
search | string | No | Match by session name. |
sortBy | string | No | createdAt, updatedAt, or name. |
sortOrder | string | No | asc or desc. |
limit | number | No | Results per page (Default 25, max 200). |
page | number | No | Page number (default: 1). |
get_session
Returns full details for one exploratory session: name, mission, status, assignee, linked release, attachments, linked issues, and findings.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the session. |
sessionId | string | Yes | Internal _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.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID where the session will be created. |
name | string | Yes | Session name. |
mission | string | No | Rich HTML mission or testing charter. |
sessionType | string | No | Free-text type, e.g., Exploratory, Regression. |
assigneeUserId | string | No | User _id or email address. |
releaseId | string | No | Attach session to this release. |
environment | string | No | Environment label, e.g., staging. |
state | string | No | new (default), under_review, done, or rejected. |
estimate | number | No | Estimated duration in minutes. |
tags | array | No | Array of tag strings, e.g., ["exploratory", "auth"]. Not comma-separated. |
linkedIssues | array | No | Linked 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.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string | Yes | The project ID containing the session. |
sessionId | string | Yes | Internal _id or counter-style ID (e.g., SES-12). |
updates | object | Yes | Fields to update: name, mission, sessionType, environment, releaseId, assigneeUserId, state, estimate, tags, linkedIssues. Pass status="closed" to close the session. |