Skip to main content

Use cases & workflows

TestingBot MCP turns natural language into real testing work. You describe a goal to your AI client and the agent decides which TestingBot tools to call, in what order, to get it done. This page walks through the most common workflows: each scenario lists the goal, an example prompt you could give your agent, and the sequence of tools the agent would typically run behind the scenes.

You never call these tools by hand, your client does. For the full list of tools and their parameters, see the Tool reference. If you have not set the server up yet, start with Setup & installation and Authentication.

All of these workflows run on TestingBot's cloud grid through one locally-running server. The main @testingbot/mcp-server package handles your account, tests, builds, storage and screenshots; it bundles @testingbot/automation-mcp, which drives live browser and mobile sessions. You don't install browsers, emulators or Appium locally. See the MCP overview for the big picture.

1. Automate a real desktop browser

Goal: open a real desktop browser on TestingBot's cloud, navigate to a page and interact with it (click, type, read text and assert), all from natural language.

"Open Chrome on Windows 11, go to my staging login page, sign in with test@example.com / hunter2, and tell me whether the dashboard heading appears."

A typical tool sequence the agent runs:

  1. tb_openBrowser: start a Chrome session on WIN11; returns a sessionId and a live-view URL.
  2. tb_navigate: load the staging login page.
  3. tb_snapshot: get a structured summary of the page so the agent knows what to interact with.
  4. tb_type: fill the email and password fields.
  5. tb_click: submit the form.
  6. tb_getText: read the dashboard heading to confirm the login worked.
  7. tb_closeBrowser: end the session and free your minutes.

The same browser-automation tools work for desktop and mobile browsers, the difference is the capabilities passed to tb_openBrowser. You can watch the whole run live (see Watch or take over a session).

2. Mobile browser on an emulator/simulator

Goal: test your mobile web experience on Android or iOS without owning the hardware. Emulators and simulators are the default, they are cheaper and plentiful, which makes them ideal for everyday responsive and functional checks.

"Open Chrome on an Android emulator (Google Pixel 9), load testingbot.com and check that the mobile menu button is visible."

A typical tool sequence:

  1. getDevices: (optional) list the mobile devices that are available.
  2. tb_openBrowser: with platform Android, deviceName "Google Pixel 9" and realDevice: false (the default). Providing a deviceName switches the session to mobile.
  3. tb_navigate: load the URL.
  4. tb_snapshot / tb_getAttribute: inspect the page and confirm the menu button is present.
  5. tb_closeBrowser: end the session.

Leaving realDevice at its default (false) runs on an emulator (Android) or simulator (iOS). This is the right choice for most mobile-web testing. Browse the full device catalog at https://testingbot.com/device.

3. Mobile browser on a physical real device

Goal: run your mobile web test on real hardware when you need true GPU rendering, sensors, or the genuine mobile Chrome/Safari engine, not an emulator approximation.

"Open Safari on a real iPhone 15 Pro running iOS 17, go to my checkout flow and read back the total price element."

A typical tool sequence:

  1. getDevices: check which real devices and OS versions are currently free.
  2. tb_openBrowser: with platform iOS, deviceName "iPhone 15 Pro", platformVersion "17" and realDevice: true.
  3. tb_navigate: load the checkout flow.
  4. tb_getText: read the total price element.
  5. tb_closeBrowser: end the session.

Real devices are a shared, finite resource. When realDevice: true and the requested device or OS version is busy or not offered, tb_openBrowser runs a pre-flight check and returns guidance without starting (and billing) a session. It will suggest waiting for the device to free up, picking an available alternative device/version, or falling back to an emulator/simulator. Your agent can act on that guidance and retry.

4. Native mobile app testing

Goal: test a native Android (.apk) or iOS (.ipa) app, not a mobile website. Upload the build to TestingBot storage, then start an Appium session against it.

"Upload the app at /Users/me/builds/app-release.apk to TestingBot, then start a native Android session with it."

A typical tool sequence:

  1. uploadFile: upload the local .apk/.ipa/.zip by absolute path. (Use uploadRemoteFile if the build lives at a URL.) This returns an app URL like tb://<id>.
  2. getStorageFiles: (optional) confirm the upload and look up the app URL.
  3. appium_session_management: action: "create", platform: "android", with capabilities including appium:app="tb://<id>", appium:deviceName and appium:platformVersion.
  4. appium_session_management: action: "list" / "select" / "delete" to manage and end sessions.

Native app sessions are managed by appium_session_management (proxied to the official Appium MCP). For mobile browser testing, use tb_openBrowser with a deviceName instead, see scenarios 2 and 3 above.

5. Cross-browser screenshots

Goal: capture how a single URL renders across many browsers and operating systems at once for fast visual comparison, without opening interactive sessions.

"Take full-page screenshots of testingbot.com in Chrome on Windows 11 and Safari on macOS, then give me the image links."

A typical tool sequence:

  1. getBrowsers: (optional) confirm valid browserName/version/os combinations.
  2. takeScreenshot: pass the url and a browsers array (each entry has browserName, optional version and os). Optionally set resolution, waitTime and fullPage. Returns a job id.
  3. retrieveScreenshots: pass the screenshotId (the job id) to get the captured image URLs.
  4. getScreenshotList: (optional) list earlier screenshot jobs.

This is a batch, fire-and-collect flow: takeScreenshot queues the job and retrieveScreenshots fetches the results once they are ready.

6. Drive a session with Playwright/Puppeteer via CDP

Goal: get a remote cloud browser plus a Chrome DevTools Protocol (CDP) endpoint so your own Playwright or Puppeteer scripts can connect to a TestingBot browser.

"Start a CDP-enabled Chrome session on Windows 11 and give me the CDP URL so I can connect Playwright to it."

A typical tool sequence:

  1. createCdpSession: pass browserName and platform (and optionally browserVersion, screenResolution, timeZone, name, build, extraCapabilities). Returns a remote browser and a CDP URL.
  2. Connect your Playwright/Puppeteer code to the returned CDP URL and run your script.
  3. getTests / getTestDetails: review the run afterwards on TestingBot.

Use this when you already have framework code and just want it pointed at the TestingBot grid, rather than driving the browser through the tb_* automation tools.

7. Watch or take over a session

Goal: watch an automation session in real time, or step in and drive it manually when something needs a human.

"Open a Chrome session on Windows 11 and give me the live link so I can watch what the agent is doing."

How it works:

  1. tb_openBrowser (or any session-starting tool) returns a live-view URL of the form https://testingbot.com/tests/<sessionId>/live?auth=<hash>.
  2. Open that URL in your browser to watch the session live; you can interact with it directly to take over.
  3. tb_listSessions: list active automation sessions if you lose track of which is running.
  4. stopTest or tb_closeBrowser, stop the session when you are done.

Every automation session returns its own live-view URL, so you can monitor or intervene at any point. This is useful for one-time captchas, MFA prompts, or simply seeing the agent's actions as they happen.

8. Inspect & debug a run

Goal: figure out why a test failed by pulling its details and logs after the fact.

"Show me my last 5 tests, then pull the details and failure logs for the one that failed."

A typical tool sequence:

  1. getTests: list recent tests (paginated via offset/limit) to find the session in question.
  2. getTestDetails: full detail for a single session by sessionId.
  3. getFailureLogs: fetch and filter session logs by sessionId; narrow with logTypes (selenium, browser, chrome, vm, appium) and failuresOnly: true.
  4. updateTest: (optional) mark the test passed/failed or update its name/build once you know the outcome.

Working with builds instead of individual tests? Use getBuilds and getTestsForBuild to drill from a build down to its sessions, then debug each one the same way.

For the complete catalog of tools and every parameter referenced above, see the Tool reference. If a workflow misbehaves, the Troubleshooting guide covers the most common issues, and the FAQ answers the rest.

Was this page helpful?
Last updated
TestingBot Docs