---
title: Tool reference | TestingBot MCP
description: 'Complete reference for every TestingBot MCP tool: authentication, browsers,
  tests, builds, storage, Maestro, Espresso and XCUITest runs, screenshots, live testing,
  CDP, tunnels.'
source_url:
  html: https://testingbot.com/support/ai/mcp/tools
  md: https://testingbot.com/support/ai/mcp/tools.md
---

# Tool reference

This page documents every tool exposed by the TestingBot MCP server. You never call these tools by hand, your AI client (Claude, Cursor, VS Code, Windsurf, and others) calls them on your behalf when you describe what you want in plain language. The names and parameters below are useful when you want to know exactly what an agent can do, or to phrase a prompt precisely.

The tools come from two bundled packages. `@testingbot/mcp-server` handles your account and orchestration (tests, builds, storage, App Automate runs for Maestro, Espresso and XCUITest, screenshots, live sessions, team, tunnels, logs and project scaffolding). `@testingbot/automation-mcp`, which is bundled automatically, drives live browser and mobile sessions over WebDriver and proxies native app testing to Appium. See [Setup & installation](https://testingbot.com/support/ai/mcp/setup) to connect the server, and [Use cases & workflows](https://testingbot.com/support/ai/mcp/use-cases) for end-to-end examples that chain these tools together.

Every tool below carries an example prompt. You do not have to phrase it that way, it is there to show the kind of request that resolves to that tool. Parameters are passed by your AI client, not typed by you. If a tool replies with _“No TestingBot credentials configured. Run the tb\_login tool…”_, authenticate first, see [Authentication](https://testingbot.com/support/ai/mcp/authentication).

## Authentication

Logs you in without pasting an API key. After a successful login, credentials are written to `~/.testingbot/credentials` and used automatically, no restart needed. Read more on the [Authentication](https://testingbot.com/support/ai/mcp/authentication) page.

| Tool | Description |
| --- | --- |
| `tb_login` | Browser or device-code login, no key paste required. |

### tb\_login

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `mode` | string | No | `auto` | Login flow: `auto` (loopback on a desktop, device on headless), `loopback` (RFC 8252 local callback), or `device` (RFC 8628 short code at [https://testingbot.com/device](https://testingbot.com/device)). |

**Example prompt:** _“Log in to TestingBot”_

## Browser & device

Discover which browsers, platforms and mobile devices are available before you start a session.

### getBrowsers

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | string | No | – | Filter the list: `web` or `mobile`. Omit for all. |

**Example prompt:** _“Which Chrome versions can I run on Windows 11?”_

### getDevices

Lists mobile devices (real devices plus emulators/simulators) with their current availability. Takes no parameters.

**Example prompt:** _“Which real iPhones are free right now?”_

## Tests

Browse, inspect and manage the test sessions in your account.

### getTests

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `limit` | number | No | `10` | Number of tests to return (max 100). |

**Example prompt:** _“List my last 10 TestingBot tests”_

### getTestDetails

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The session to fetch full details for. |

**Example prompt:** _“Show me the full details of my most recent failed test, with the video and logs”_

### updateTest

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The session to update. |
| `name` | string | No | – | New test name. |
| `status` | string | No | – | Mark the test as `passed` or `failed`. |
| `build` | string | No | – | Associate the test with a build. |
| `extra` | string | No | – | Additional metadata as a JSON string. |

**Example prompt:** _“Mark that session as failed and rename it to Checkout regression”_

### deleteTest

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The session to delete. |

**Example prompt:** _“Delete the session I just started by mistake”_

### stopTest

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The running session to stop. |

**Example prompt:** _“Stop the session that is still running”_

## Builds

Group related tests into builds and manage them.

### getBuilds

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `limit` | number | No | `10` | Number of builds to return (max 100). |

**Example prompt:** _“List my last 5 builds”_

### getTestsForBuild

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `buildId` | string | Yes | – | The build whose tests you want to list. |

**Example prompt:** _“Which tests are in the build called nightly?”_

### deleteBuild

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `buildId` | string | Yes | – | Deletes the build and all of its tests. |

**Example prompt:** _“Delete the build called scratch-run and everything in it”_

## Storage

Upload and manage native mobile app binaries (`.apk`, `.ipa`, `.zip`) so they can be installed on devices for native app testing.

### uploadFile

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `localFilePath` | string | Yes | – | Absolute path to a local `.apk`/`.ipa`/`.zip`. |

**Example prompt:** _“Upload /Users/me/builds/app-release.apk to TestingBot storage”_

### uploadRemoteFile

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `remoteUrl` | string | Yes | – | An http/https URL to fetch and store (SSRF-guarded). |

**Example prompt:** _“Upload the build at https://ci.example.com/artifacts/app.ipa to my TestingBot storage”_

### getStorageFiles

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `limit` | number | No | `10` | Number of files to return (max 100). |

**Example prompt:** _“Which app builds do I have in storage?”_

### deleteStorageFile

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `appUrl` | string | Yes | – | The stored app reference to delete. |

**Example prompt:** _“Delete tb://app123 from storage”_

## App Automate: Maestro

Run [Maestro](https://testingbot.com/support/app-automate/maestro) flows on TestingBot real devices, emulators and simulators. The agent uploads your app, uploads (or writes) the flow YAML, starts a run, and polls until it finishes.

Maestro runs are **asynchronous** : `runMaestroTest` returns a run ID immediately and does not block while devices execute. The agent then polls `getMaestroRunStatus` and fetches `getMaestroRunResults` once the run completes.

| Tool | Description |
| --- | --- |
| `uploadMaestroApp` | Upload the app under test. Returns a project id. |
| `uploadMaestroFlows` | Upload the flow YAML for a project, from disk or inline. |
| `runMaestroTest` | Start a run. Returns a run id immediately. |
| `getMaestroRunStatus` | Poll per-flow progress. |
| `getMaestroRunResults` | Final outcomes plus the JUnit XML report. |
| `getMaestroFlowDetails` | Errors, step-level report, video, screenshots and device logs for one flow. |
| `cancelMaestroRun` | Cancel a running run. |
| `retryMaestroRun` | Retry a whole run, or a single failed flow. |
| `uploadMaestroCompanionApp` | Upload a companion app to install alongside the app under test. |
| `listMaestroProjects` | Find existing projects instead of re-uploading. |
| `listMaestroRuns` | List runs, or look them up by run name. |
| `maestroCheatSheet` | Maestro YAML syntax reference for the agent. |

### uploadMaestroApp

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `localFilePath` | string | Yes | – | Local path to the `.apk`, `.aab`, `.ipa` or zipped `.app`. |

Returns a **project id** that every other Maestro tool takes. Uploads are deduplicated by checksum, so re-running with an unchanged binary reuses the existing project instead of uploading again.

**Example prompt:** _“Upload ./build/app.apk for Maestro testing”_

### uploadMaestroFlows

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectId` | number | Yes | – | Project id from `uploadMaestroApp`. |
| `flowsPath` | string | No | – | Directory of `.yaml`/`.yml` flows (structure preserved, so `runFlow` subflows keep resolving), or a pre-built `.zip`. |
| `flows` | array | No | – | Inline flows as `{ fileName, content }` objects, for flows the agent writes itself. |

Each upload replaces the flows previously uploaded for that project.

**Example prompt:** _“Upload the flows in ./flows to that project”_

### runMaestroTest

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectId` | number | Yes | – | Project id from `uploadMaestroApp`. |
| `platformName` | string | Yes | – | `Android` or `iOS`. |
| `deviceName` | string | No | any device | Device name, wildcards and regex supported, e.g. `Pixel 8`, `iPhone 1[4-6]`, `*`. |
| `version` | string | No | – | OS version, e.g. `14`. |
| `realDevice` | boolean | No | `false` | Run on a physical device instead of an emulator/simulator. Required for `.ipa` apps. |
| `name` | string | No | – | Run name shown in the dashboard, and the value `listMaestroRuns` looks up. |
| `env` | object | No | – | Environment variables passed to the flows. |
| `includeTags` | array | No | – | Only run flows carrying these Maestro tags. |
| `excludeTags` | array | No | – | Skip flows carrying these Maestro tags. |
| `shardSplit` | number | No | – | Split the flows across this many parallel devices (1–10). |
| `otherApps` | array | No | – | Up to 4 companion app URLs (`tb://` or `http(s)://`) installed alongside the app under test. |

**Example prompt:** _“Run my Maestro flows on a real Pixel 8 with Android 14”_

### getMaestroRunStatus

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectId` | number | Yes | – | The project to inspect. |
| `runId` | number | No | – | A specific run. Omit it to list the runs of the latest execution. |

Per-flow statuses are `WAITING`, `READY` (running), `DONE`, `FAILED` and `CANCELLED`, with failures listed first. The flow ids in this output are what `getMaestroFlowDetails` and `retryMaestroRun` take.

**Example prompt:** _“How is that Maestro run doing?”_

### getMaestroRunResults

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectId` | number | Yes | – | The project. |
| `runId` | number | Yes | – | The completed run. |

Returns per-flow outcomes, failures first with error messages and video links, plus the JUnit XML report.

**Example prompt:** _“Give me the results of the Maestro run now that it has finished”_

### getMaestroFlowDetails

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectId` | number | Yes | – | The project. |
| `runId` | number | Yes | – | The run. |
| `flowId` | number | Yes | – | The flow, taken from `getMaestroRunStatus`. |

This is the debugging tool: error messages, the step-level JUnit report and links to the video, screenshots and device logs. Fetch it for a failed flow, fix the YAML, upload the flows again, then retry.

**Example prompt:** _“Why did the checkout flow fail? Show me the error and the video”_

### cancelMaestroRun

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectId` | number | Yes | – | The project. |
| `runId` | number | Yes | – | The run to cancel. |

**Example prompt:** _“Cancel the Maestro run I just started”_

### retryMaestroRun

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectId` | number | Yes | – | The project. |
| `runId` | number | Yes | – | The run to retry. |
| `flowId` | number | No | – | Retry only this flow instead of the whole run. |

**Example prompt:** _“Fix the login flow and re-run just that one”_

### uploadMaestroCompanionApp

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `localFilePath` | string | Yes | – | Local path to the companion `.apk`, `.aab`, `.ipa` or `.zip`. |

Returns a `tb://` app URL to pass in the `otherApps` parameter of `runMaestroTest` (max 4 per run).

**Example prompt:** _“Upload ./build/mock-backend.apk as a companion app for the run”_

### listMaestroProjects

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `count` | number | No | `10` | Number of projects to return (max 100). |

Newest first, with app details, flow names and run ids, so the agent can reuse a project id rather than re-uploading an app.

**Example prompt:** _“What Maestro projects do I already have on my account?”_

### listMaestroRuns

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `buildName` | string | No | – | Look up runs with this exact run name instead of listing all runs. |
| `offset` | number | No | `0` | Pagination offset. Ignored when `buildName` is set. |
| `count` | number | No | `10` | Number of runs to return (max 100). Ignored when `buildName` is set. |

Returns `projectId` and `runId` pairs. The `buildName` lookup is what makes prompts like _“rerun whatever failed in last night's nightly build”_ work.

**Example prompt:** _“Find the Maestro run named nightly and tell me what failed in it”_

### maestroCheatSheet

Returns a Maestro YAML syntax reference: file structure, commands, selectors and the TestingBot run workflow. Takes no parameters. Agents call this before writing or fixing flows, so the YAML they produce matches what Maestro actually accepts.

**Example prompt:** _“Write me a Maestro flow that logs in and adds an item to the cart”_

Maestro tooling requires `@testingbot/mcp-server` 1.1.0 or later. If your agent reports that these tools do not exist, update the server, see [Setup & installation](https://testingbot.com/support/ai/mcp/setup).

## App Automate: Espresso & XCUITest

Run pre-built [Espresso](https://testingbot.com/support/app-automate/espresso) (Android) and [XCUITest](https://testingbot.com/support/app-automate/xcuitest) (iOS) suites on TestingBot devices. Every tool takes a `framework` parameter, `espresso` or `xcuitest`, and follows the same asynchronous start, poll, fetch pattern as Maestro.

| Tool | Description |
| --- | --- |
| `uploadAppAutomateApp` | Upload the app under test. Returns a project id. |
| `uploadAppAutomateTests` | Upload the test suite for that project. |
| `runAppAutomateTest` | Start a run. Returns a run id immediately. |
| `getAppAutomateRunStatus` | Poll run progress. |
| `getAppAutomateRunResults` | Per-run outcomes plus the JUnit XML report. |

### uploadAppAutomateApp

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `framework` | string | Yes | – | `espresso` or `xcuitest`. |
| `localFilePath` | string | Yes | – | The app under test: `.apk`/`.aab` for Espresso, `.ipa`/`.zip` for XCUITest. |

Returns the project id used by the other two App Automate tools. For Maestro flows, use `uploadMaestroApp` instead.

**Example prompt:** _“Upload ./app/build/outputs/apk/debug/app-debug.apk for an Espresso run”_

### uploadAppAutomateTests

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `framework` | string | Yes | – | `espresso` or `xcuitest`. |
| `projectId` | number | Yes | – | Project id from `uploadAppAutomateApp`. |
| `localFilePath` | string | Yes | – | The instrumented test `.apk` for Espresso, or the zipped XCUITest runner bundle (`.zip`). |

**Example prompt:** _“Upload the instrumented test APK for that project”_

### runAppAutomateTest

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `framework` | string | Yes | – | `espresso` or `xcuitest`. |
| `projectId` | number | Yes | – | Project id from `uploadAppAutomateApp`. |
| `deviceName` | string | No | any device | Device name, wildcards and regex supported, e.g. `Galaxy S23`, `iPhone 1[4-6]`, `*`. |
| `version` | string | No | – | OS version, e.g. `14`. |
| `realDevice` | boolean | No | `false` | Run on a physical device instead of an emulator/simulator. |
| `name` | string | No | – | Run name shown in the dashboard. |
| `build` | string | No | – | Build identifier used to group runs. |
| `locale` | string | No | – | Locale for the run, e.g. `fr_FR`. |
| `timeZone` | string | No | – | Time zone for the run, e.g. `Europe/Brussels`. |
| `testClasses` | array | No | – | Espresso only: run only these fully qualified test classes. |
| `skipTestClasses` | array | No | – | Espresso only: skip these test classes. |
| `packages` | array | No | – | Espresso only: run only these packages. |
| `annotations` | array | No | – | Espresso only: run only tests carrying these annotations. |
| `testRunner` | string | No | – | Espresso only: custom instrumentation runner. |

**Example prompt:** _“Run the Espresso suite on a real Galaxy S23, only the com.example.LoginTest class”_

### getAppAutomateRunStatus

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `framework` | string | Yes | – | `espresso` or `xcuitest`. |
| `projectId` | number | Yes | – | The project to inspect. |
| `runId` | number | No | – | A specific run. Omit it to list every run in the project. |

Statuses are `WAITING`, `READY` (running), `DONE` and `FAILED`. Each run also reports its Appium session id.

**Example prompt:** _“Is my XCUITest run finished yet?”_

### getAppAutomateRunResults

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `framework` | string | Yes | – | `espresso` or `xcuitest`. |
| `projectId` | number | Yes | – | The completed project. |
| `runId` | number | No | – | XCUITest only: fetch the JUnit report of this single run. |

**Example prompt:** _“Show me the JUnit results for that Espresso project”_

Because each Espresso and XCUITest run surfaces its Appium session id, the session tools work on them too: pass that id to [`getTestDetails`](https://testingbot.com#tests) for the video and screenshots, or to [`getFailureLogs`](https://testingbot.com#logs) for the device and Appium logs.

## Screenshots

Capture a URL across multiple browsers and platforms for cross-browser visual checks.

### takeScreenshot

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `url` | string | Yes | – | The page to capture. |
| `browsers` | array | Yes | – | Array of `{ browserName, version?, os }` targets. |
| `resolution` | string | No | `1920x1080` | Screen resolution to render at. |
| `waitTime` | number | No | `5` | Seconds to wait before capture (0–60). |
| `fullPage` | boolean | No | `false` | Capture the full scrollable page. |

Returns a job id that you pass to `retrieveScreenshots`.

**Example prompt:** _“Take full-page screenshots of testingbot.com in Chrome on Windows 11 and Safari on macOS”_

### retrieveScreenshots

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `screenshotId` | string | Yes | – | The job id returned by `takeScreenshot`. |

**Example prompt:** _“Are those screenshots ready? Give me the image links”_

### getScreenshotList

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `offset` | number | No | `0` | Pagination offset. |
| `limit` | number | No | `10` | Number of jobs to return (max 100). |

**Example prompt:** _“List my recent screenshot jobs”_

## User

Read and update your account profile.

### getUserInfo

Returns account information, name, plan, company, country, available seconds and concurrency. Takes no parameters. Note: `getUserInfo` does not return an email field.

**Example prompt:** _“How many testing minutes do I have left?”_

### updateUserInfo

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `firstName` | string | No | – | New first name. |
| `lastName` | string | No | – | New last name. |
| `email` | string | No | – | New email address. |

**Example prompt:** _“Update the last name on my profile to De Vries”_

## Live testing

Start an interactive, manual live session you can watch and control. Each session returns a live-view URL of the form `https://testingbot.com/tests/<sessionId>/live?auth=<hash>`.

### startLiveSession

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `platformType` | string | Yes | – | `desktop` or `mobile`. |
| `desiredURL` | string | Yes | – | The URL to open in the session. |
| `desiredOS` | string | Yes | – | Operating system to run on. |
| `desiredOSVersion` | string | Yes | – | OS version. |
| `desiredBrowser` | string | No | – | Browser to launch (desktop). |
| `desiredBrowserVersion` | string | No | – | Browser version (desktop). |
| `desiredDevice` | string | No | – | Device name (mobile). |

**Example prompt:** _“Start a live session on Windows 11 in Chrome and open my staging site”_

### startDesktopLiveSession

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `desiredURL` | string | Yes | – | The URL to open. |
| `desiredOS` | string | Yes | – | `Windows`, `Mac` or `Linux`. |
| `desiredOSVersion` | string | Yes | – | OS version. |
| `desiredBrowser` | string | Yes | – | `chrome`, `firefox`, `safari`, `edge` or `ie`. |
| `desiredBrowserVersion` | string | No | `latest` | Browser version. |

**Example prompt:** _“Give me a manual Safari session on macOS Ventura pointed at example.com”_

### startMobileLiveSession

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `desiredURL` | string | Yes | – | The URL to open. |
| `desiredOS` | string | Yes | – | `android` or `ios`. |
| `desiredOSVersion` | string | Yes | – | OS version. |
| `desiredDevice` | string | Yes | – | The device to run on. |

**Example prompt:** _“Open a live session on an iPhone 15 Pro and load my checkout page”_

## Team

Inspect your team settings, usage and members.

| Tool | Param | Required | Description |
| --- | --- | --- | --- |
| `getTeam` | – | – | Team settings and usage. No parameters. |
| `getUsersInTeam` | – | – | List all team members. No parameters. |
| `getUserFromTeam` | `userId` | Yes | Fetch a single team member by id. |

**Example prompt:** _“Show my team's usage this month and list everyone in it”_

## CDP

Spin up a remote browser exposing a Chrome DevTools Protocol endpoint, so you can drive it with Puppeteer or Playwright. See the Playwright/Puppeteer example in [Use cases & workflows](https://testingbot.com/support/ai/mcp/use-cases).

### createCdpSession

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `browserName` | string | Yes | – | Browser to launch. |
| `browserVersion` | string | No | `latest` | Browser version. |
| `platform` | string | Yes | – | Platform to run on. |
| `screenResolution` | string | No | – | Screen resolution. |
| `timeZone` | string | No | – | Time zone for the session. |
| `name` | string | No | – | Session name. |
| `build` | string | No | – | Build to associate the session with. |
| `extraCapabilities` | object | No | – | Additional WebDriver capabilities. |

**Example prompt:** _“Start a CDP-enabled Chrome session on Windows 11 and give me the WebSocket URL”_

## Tunnels

Manage TestingBot Tunnels for testing local or firewalled sites.

| Tool | Param | Required | Description |
| --- | --- | --- | --- |
| `getTunnelList` | – | – | List active tunnels. No parameters. |
| `deleteTunnel` | `tunnelId` | Yes | Stop an active tunnel by id. |

**Example prompt:** _“List my active tunnels and stop the one I left running this morning”_

## Logs

Fetch and filter the logs for a session, ideal for debugging a failing run.

### getFailureLogs

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The session whose logs you want. |
| `logTypes` | array | No | – | Any of `selenium`, `browser`, `chrome`, `vm`, `appium`. |
| `failuresOnly` | boolean | No | `false` | Return only failure-related entries. |
| `maxBytesPerLog` | number | No | `50000` | Truncate each log (1,000–1,000,000 bytes). |
| `timeoutMs` | number | No | `15000` | Fetch timeout (1,000–60,000 ms). |

**Example prompt:** _“Pull just the failure lines from the Appium and device logs for that session”_

## Project

Detect the test framework in a local project and scaffold a ready-to-use TestingBot configuration.

### listTestFiles

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectRoot` | string | Yes | – | Root directory of the project to scan. |
| `maxDepth` | number | No | `8` | How deep to recurse (1–15). |
| `maxResults` | number | No | `200` | Maximum files to return (1–2000). |

**Example prompt:** _“What test files are in this project?”_

### setupTestingBot

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `projectRoot` | string | Yes | – | Root directory of the project. |
| `frameworkOverride` | string | No | – | Force a framework instead of auto-detecting. |

Generates a ready-to-paste TestingBot config for the detected framework, Playwright, Cypress, WebdriverIO, Selenium (JS), Nightwatch or Puppeteer.

**Example prompt:** _“Set this project up to run on TestingBot”_

## Browser automation

These tools come from the bundled `@testingbot/automation-mcp` package and drive a live browser session over WebDriver. They work for desktop browsers and for mobile browsers (on emulators/simulators or real devices). Every session starts with `tb_openBrowser`, which returns a `sessionId` you pass to the other tools, plus a live-view URL (`https://testingbot.com/tests/<sessionId>/live?auth=<hash>`) you can open to watch or take over.

### tb\_openBrowser

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `browserName` | string | Yes | – | `chrome`, `firefox`, `edge` or `safari`. |
| `browserVersion` | string | No | `latest` | Browser version (desktop only). |
| `platform` | string | Yes | – | Desktop codes like `WIN11`/`VENTURA`, or `Android`/`iOS` for mobile. |
| `deviceName` | string | No | – | Mobile only (e.g. `Google Pixel 9`, `iPhone 15 Pro`). Its presence switches the session to mobile. |
| `platformVersion` | string | No | – | Mobile OS version. |
| `automationName` | string | No | `UiAutomator2`/`XCUITest` | Mobile automation engine. |
| `realDevice` | boolean | No | `false` | `true` = physical device, `false` = emulator/simulator. |
| `name` | string | No | – | Session name. |
| `build` | string | No | – | Build to group the session under. |
| `screenResolution` | string | No | – | Screen resolution (desktop only). |

**Example prompt:** _“Open Chrome on Windows 11”_

Real-device pre-flight: if `realDevice:true` and the requested device or version is busy or not offered, `tb_openBrowser` returns guidance (wait, use an emulator, or pick an available alternative) **without** starting a session. See [Use cases](https://testingbot.com/support/ai/mcp/use-cases) and [Troubleshooting](https://testingbot.com/support/ai/mcp/troubleshooting).

### tb\_navigate

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `url` | string | Yes | – | The URL to navigate to. |

**Example prompt:** _“Go to my staging login page”_

### tb\_snapshot

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `bodyChars` | number | No | `5000` | Body text characters to include (500–50,000). |

Returns a structured summary of the page: title, headings, actionable elements and body text.

**Example prompt:** _“What is on the page right now?”_

### tb\_click

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `by` | string | No | `css` | Locator strategy: `css`, `xpath`, `id`, `name`, `tag`, `class`, `linkText`, `partialLinkText`. |
| `value` | string | Yes | – | The locator value. |
| `timeoutMs` | number | No | `5000` | Wait timeout (100–30,000 ms). |

**Example prompt:** _“Click the Sign in button”_

### tb\_type

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `by` | string | No | `css` | Locator strategy. |
| `value` | string | Yes | – | The locator value of the field. |
| `text` | string | Yes | – | Text to type. |
| `clearFirst` | boolean | No | `true` | Clear the field before typing. |
| `pressEnter` | boolean | No | `false` | Press Enter after typing. |

**Example prompt:** _“Type test@example.com into the email field and press Enter”_

### tb\_getText

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `by` | string | No | `css` | Locator strategy. |
| `value` | string | Yes | – | The locator value. |
| `timeoutMs` | number | No | `5000` | Wait timeout. |

**Example prompt:** _“Read back the dashboard heading”_

### tb\_getAttribute

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `by` | string | No | `css` | Locator strategy. |
| `value` | string | Yes | – | The locator value. |
| `attribute` | string | Yes | – | The attribute name to read. |
| `timeoutMs` | number | No | `5000` | Wait timeout. |

**Example prompt:** _“Is the submit button still disabled?”_

### tb\_executeScript

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `script` | string | Yes | – | JavaScript to run in the page. |
| `args` | array | No | `[]` | Arguments passed to the script. |

**Example prompt:** _“Scroll to the bottom of the page and tell me the document height”_

### tb\_screenshot

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `savePath` | string | No | OS temp dir | A `.png` path or directory to save to. |

Returns an inline image _and_ saves a file, returning a clickable `file://` link. Many clients do not render inline tool images, so open the saved file if you do not see the screenshot in chat.

**Example prompt:** _“Take a screenshot of what the browser is showing now”_

### tb\_pressKey

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | The active session. |
| `key` | string | Yes | – | A W3C key or chord, e.g. `Enter` or `Control+A`. |

**Example prompt:** _“Press Escape to close the modal”_

### tb\_closeBrowser

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `sessionId` | string | Yes | – | Ends the session and frees minutes. |

**Example prompt:** _“Close the session”_

### tb\_listSessions

Lists active automation sessions. Takes no parameters.

**Example prompt:** _“Which automation sessions do I have open?”_

## Mobile native apps

For testing native iOS/Android apps (not mobile browsers, use `tb_openBrowser` for those), the automation package proxies to the official appium-mcp. Upload your app first with `uploadFile`, then reference it as `appium:app="tb://<id>"`.

### appium\_session\_management

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `action` | string | Yes | – | One of `create`, `delete`, `list`, `detach`, `select`. |
| `platform` | string | For create | – | `ios` or `android`. |
| `capabilities` | string | No | – | JSON string for `create`: `appium:deviceName`, `appium:platformVersion`, `appium:app="tb://<id>"`. |
| `sessionId` | string | No | – | Required for `delete`, `detach` and `select`. |

Ready to put these together? See [Use cases & workflows](https://testingbot.com/support/ai/mcp/use-cases) for full tool sequences, or return to the [MCP overview](https://testingbot.com/support/ai/mcp).

**Example prompt:** _“Start a native Android session with the app I just uploaded”_

## Looking for more help?

Have questions or need more information? Reach out via email or Slack.

[Email us](https://testingbot.com/contact/new) [Join our Slack](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)