Tools Reference
Find the complete specification for all MCP tools exposed by the TestDino MCP Server here.
Each tool includes a functional description, parameter list, usage examples, expected responses, and notes based on your current implementation.
1. health
Verify server availability and validate the TESTDINO_API_KEY configuration.
- The
healthtool is the first tool to run after installation. - It confirms that the MCP server is running, that an API key is configured, and that the server can reach TestDino and retrieve project information.
- Use this tool to validate installation and diagnose connectivity or authentication issues.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name used in the greeting message. |
Example Usage
Use Cases
- Confirm that the MCP server is running.
- Validate API key and project access.
- Basic troubleshooting after installation.
2. list_testruns
Browses and filters test runs to find specific executions.
- Returns test run summaries with rich filtering support.
- Result items include run metadata, duration, status, environment, branch, author, PR, and test statistics (passed, failed, skipped, flaky, timedOut, totalAttempts, retriedTests).
- Use this tool to answer questions like:
What tests ran on the develop branch? Show all runs from the last 3 days.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
by_branch | string | No | - | Git branch name, e.g., main, develop. |
by_time_interval | string | No | - | Time filters: 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 | 20 | Results per page. Max 1000. |
page | number | No | 1 | Page number for pagination. |
get_all | boolean | No | false | Retrieve all results up to 1000. |
by_counter | number | No | - | Filter by run counter number. |
Note:
- Filters can be combined.
- Pagination uses
pageandlimit.get_all=truefetches up to 1000 records.
Example Usage
Use Cases
- Monitoring recent runs.
- Branch-level analysis.
- PR verification.
- Time-based trend checks.
- Author-specific run audits.
3. get_run_details
Return a full report for one or more test runs, including suites, cases, statistics, metadata, and raw JSON.
- Provides a comprehensive view of a test run.
- Output includes project info, complete statistics, failure categories, suite-level breakdowns, test case details, rerun metadata, and the raw JSON.
- Use this to debug specific runs, inspect reruns, or extract per-suite and per-test details.
- Accepts a single run ID, a counter, or a comma-separated batch (max 20).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
testrun_id | string | No | Single ID or comma-separated IDs for batch lookup (max 20). |
counter | number | No | Sequential run counter number. |
Example Usage
4. list_testcase
List test cases across runs with comprehensive filtering, to find failed, flaky, or slow tests.
-
Direct identification is supported through
by_testrun_idorcounter. -
You can also locate test cases using run-level filters such as branch, commit, author, environment, or time interval.
-
In this workflow, the tool first identifies all matching test runs, then returns the test cases from those runs.
-
It supports additional case-level filters, including status, spec file, browser, tags, error category, runtime thresholds, artifacts presence, error messages, and attempt number.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
by_testrun_id | string | No* | Single or multiple run IDs (comma-separated, max 20). |
counter | number | No* | Run counter. 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 | Which attempt number to filter by. |
by_branch | string | No | Branch name; first filters runs, then returns cases. |
by_time_interval | string | No | Time interval: supports 1d, 3d, weekly, monthly, and date ranges. |
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. |
*At least one of the test run identification methods or a test run filter must be present.
Example Usage
Use Cases
- Failure triage.
- Flaky test detection.
- Performance and runtime analysis.
- Artifact discovery for debugging.
5. get_testcase_details
Retrieve detailed information for a single test case to support debugging.
Returns full error messages, stack traces, test steps, console logs, retry attempts, artifacts (screenshots, videos, traces), metadata, and performance metrics.
Identify a test case by testcase_id, or by testcase_name combined with testrun_id or counter to disambiguate across runs.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
testcase_id | string | No* | Test case ID can be used alone. |
testcase_name | string | No* | Test case name must be used with testrun_id or counter. |
testrun_id | string | No | Required when using testcase_name to identify the run. |
counter | number | No | Alternative to testrun_id when using testcase_name. |
*One of testcase_id or (testcase_name + testrun_id/counter) must be provided.
Example Usage
Use Cases
- Deep debugging of failing tests.
- Reviewing retry behavior and flakiness.
- Collecting artifacts for bug reports.
6. upload_latest_local_test_runs
Upload Playwright test results from the local machine to TestDino to create a new run for analysis.
- This tool discovers Playwright report output on the local filesystem, detects git metadata (branch, commit, author), and uploads test results to TestDino.
- It supports uploading HTML reports, images, videos, traces, attachments, or full JSON bundles.
- Use it to bridge local testing and centralized test management.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
token | string | No | - | API token; optional if TESTDINO_API_KEY is set in mcp.json. |
reportDir | string | No | ./playwright-report | Path to Playwright report directory. Absolute paths recommended. |
uploadHtml | boolean | No | true | Upload HTML report bundle (includes JSON, images, videos). |
uploadImages | boolean | No | false | Upload screenshots (images). If uploadHtml is true, images are included already. |
uploadVideos | boolean | No | false | Upload test execution videos. If uploadHtml is true, videos are included already. |
uploadTraces | boolean | No | false | Upload Playwright trace files for debugging. |
uploadFiles | boolean | No | false | Upload file attachments (.md, .pdf, .txt, .log). |
uploadFullJson | boolean | No | false | Upload a full JSON bundle containing all artifacts instead of HTML. |
runtime | string | No | development | Select runtime environment: development, staging, production. |
How it finds reports
1. Report Discovery
The tool searches for a Playwright report directory in multiple locations:
- Documents
- Desktop
- Projects
- Current working directory
- Upward directory walk (up to 15 levels) to locate the nearest report folder
This ensures the upload succeeds even when users run it from nested directories.
2. Upload Process
The tool uses the tdpw CLI internally:
- Uploads test results (JSON format)
- Uploads HTML reports when
uploadHtmlis true - Optionally uploads images, videos, traces, and attachments based on parameters
This creates a complete TestDino run with full artifacts.
Command used internally
npx --yes tdpw upload <reportDir> --token=<token> [--upload-html]
Working directory is set to the git repository root.
Troubleshooting
Report Directory Not Found
Problem: The tool cannot find a playwright-report directory.
Solutions:
- Ensure Playwright tests have been executed:
npx playwright test - Confirm that the report directory exists
- Use an absolute path for
reportDir - Verify the directory structure before calling the tool