# Testim MCP

> Testim connects your end-to-end testing suite directly into your AI agent. You can manage code branches, trigger complex test runs, and analyze execution logs—all using natural conversation. This MCP lets you run full regression tests or check specific development branch health without ever opening the Testim GUI.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** automated-testing, end-to-end-testing, test-automation, qa-automation, execution-logs, test-suite

## Description

Imagine running complex quality assurance checks just by talking to your agent. This MCP brings automated E2E testing orchestration right into your chat window, letting you manage your entire test suite via conversation. Instead of navigating dashboards and clicking through multiple tabs to check logs or initiate a build, you ask your AI client to handle it all.

It lets you quickly view parallel development efforts by listing project branches, run dynamic batches based on labels, and pull the pass/fail status for any execution ID immediately after deployment. If you're working with different types of systems, Vinkius hosts this MCP in its catalog, making sure your agent can access all the necessary test details to give you a clear picture of quality. You get granular control over everything from triggering specific tests to merging branches without leaving your editor.

## Tools

### create_project_branch
Creates a brand new, isolated development branch for testing changes.

### get_execution_results
Pulls the final status and detailed outcome report from a specific test run ID.

### get_test_details
Retrieves comprehensive information about one particular automated Testim test script.

### list_project_branches
Shows a list of all active, parallel development branches within the project.

### list_tests
Provides an inventory listing of every automated test defined in your Testim project.

### merge_project_branch
Merges changes from one development branch into another target branch (like 'master').

### run_tests_by_label
Triggers a complete test run that only includes tests matching specific, defined labels.

### run_test_plan
Starts an execution for an entire predefined set of linked test plans.

### run_test_suite
Initiates a run that includes every single test within a specified, grouped test suite.

### run_specific_test
Starts an immediate test execution for one specific test script on a chosen branch.

## Prompt Examples

**Prompt:** 
```
List all branches available in my Testim project.
```

**Response:** 
```
Here are 3 branches active in your project:
- `master` (Default, ID: MSTR)
- `feature/new-checkout-flow` (ID: FTR104)
- `bugfix/login-captcha` (ID: BUG44)
Would you like to trigger test suites on any specific branch or merge one?
```

**Prompt:** 
```
Trigger a plan run for "Nightly-Regression".
```

**Response:** 
```
Test plan 'Nightly-Regression' successfully triggered.
Execution ID: `EXC-558291a`
The cloud runners are executing your plan. You can ask me to fetch the execution results and logs by providing this ID later.
```

**Prompt:** 
```
Retrieve the execution diagnostic summary for ID EXC-999333.
```

**Response:** 
```
Execution `EXC-999333` has concluded.
Status: **FAILED ❌**
Error Details: At Step 4 (Verify Cart Element). Element `#checkout-btn` could not be located on the DOM within the 10000ms timeout threshold window. Screenshot payload available in dashboard.
```

## Capabilities

### Manage Project Branches
List, create, and merge automated test development branches directly through your agent.

### Run Test Batches
Trigger full test runs by specifying defined test plans, entire suites, or filtering by specific labels.

### Check Execution Diagnostics
Retrieve the status and detailed errors for any completed test run using a unique execution ID.

### Inspect Test Inventory
View all available tests in your project or retrieve full details on a specific automated test script.

## Use Cases

### Pre-Deployment Safety Check
A Release Manager needs to know if the staging environment is stable. They ask their agent to run_test_plan 'Nightly Regression'. When the results come back, they use get_execution_results with the returned ID to confirm that every critical test passed before hitting the deploy button.

### Fixing a Bug on a Feature Branch
A Frontend Developer has written code for a new feature branch. Instead of committing and opening a full pipeline, they use run_specific_test to validate only the critical paths. This gives immediate feedback without interrupting the main development line.

### Comparing Development Lines
A QA Engineer needs to see if two separate feature branches conflict. They first list_project_branches to confirm both exist, then use merge_project_branch to simulate and validate how one branch incorporates changes from the other.

### Investigating a Failure
A developer sees an error log in chat. They ask their agent to get_test_details for that failing test ID. This quickly pulls up the full script details, allowing them to diagnose if the failure is due to code or setup.

## Benefits

- Stop copying logs. By calling get_execution_results, you instantly pull the pass/fail status for any test run ID directly into your conversation thread.
- Don't switch tools to see what's happening in development. Use list_project_branches or create_project_branch to manage and compare parallel code efforts without opening the Testim GUI.
- Run exactly what you need, nothing more. Instead of running everything, use run_tests_by_label to trigger tests that match specific functional requirements (e.g., 'checkout' or 'payment').
- Get deep insight into your test scripts using get_test_details. You can review all the technical steps and setup for any single automated script right away.
- Verify deployment safety with run_test_plan. Triggering a full plan ensures that a critical set of tests runs together, providing confidence before release.

## How It Works

The bottom line is that you use natural language prompts to control complex CI/CD testing pipelines without touching any GUI.

1. Subscribe to this MCP and provide your unique Testim Project ID and API Key.
2. Your agent connects the credentials, allowing it to access all testing tools. You then give a natural language command like 'Run tests on the latest branch'.
3. The MCP executes the required actions (like listing branches or triggering a run) and returns structured data—the pass/fail status, logs, or merge options—directly to your chat.

## Frequently Asked Questions

**How do I check the status of a test run using Testim MCP?**
You use get_execution_results by providing the unique execution ID. This tool pulls the final status, whether it passed or failed, and gives you the error details immediately.

**Can I trigger tests for only a specific area using Testim MCP?**
Yes, use run_tests_by_label. You just tell your agent which labels to target (e.g., 'payment' or 'user-login'), and the system runs only those relevant tests.

**What is the difference between running a suite and running a plan with Testim MCP?**
A test suite runs all scripts within one defined group of tests. A test plan coordinates multiple suites or sets of tests, giving you broader coverage across different feature areas.

**Do I need to use the GUI if I want to manage my branches with Testim MCP?**
No. You can list_project_branches and even merge changes using the MCP tools directly through your agent, removing the need to open the graphical user interface entirely.

**Where do I find details about a specific test script with Testim MCP?**
Use get_test_details. This tool provides all technical information on a single test script, helping you understand its prerequisites and expected behavior.