JavaScript Executor Commands
TestingBot adds custom commands to the WebDriver executeScript (JavaScript executor) call. A script that starts with tb: is not run in the browser: TestingBot handles it and answers it, so you can report a test result, throttle the network or restart an app from inside your Selenium or Appium test.
This page lists every tb: command and the platforms it works on. Where a command has its own page with more examples, the table links to it.
How to send a command
Pass the command as the script, and its arguments (if any) as the script arguments:
// Selenium / WebdriverIO (JavaScript)
await driver.executeScript('tb:test-result=passed', []);
await driver.executeScript('tb:throttle', ['3G']);
await driver.executeScript('tb:geo', [{ code: 'DE' }]);
# Python
driver.execute_script("tb:test-name=Checkout flow")
driver.execute_script("tb:locale", {"locale": "fr", "country": "FR"})
Some commands put their value in the script itself (tb:test-name=My test), others take an object as the first argument (tb:geo with { code: 'DE' }). The tables below show which form each command uses.
These commands work in Selenium and Appium (WebDriver) sessions. Playwright and Puppeteer sessions report results in their own way: see Playwright test results and Puppeteer test results.
Test details and results
These commands change the test's details in your TestingBot dashboard. They work on every platform: desktop browsers, emulators, simulators and real devices.
| Command | What it does | More |
|---|---|---|
tb:test-result=passedtb:test-result=failed
|
Marks the test as passed or failed. true and false work too. |
Test Result |
tb:test-name=... |
Sets the test's name. | Test Name |
tb:test-build=... |
Adds the test to the build with this name, and creates the build if it does not exist yet. | Test Build |
tb:test-tags=tag1,tag2 |
Adds comma-separated tags to the test. | Test Tags |
tb:test-project=... |
Files the test under the project with this name. The test's build is filed under it too, if that build has no project yet. The value may be URL-encoded. |
Test Info (the project field does the same) |
tb:test-context=... |
Adds a step with this text to the test's log, for example to mark where a test phase starts. | Test Context |
tb:test-info={...} |
Sets several details at once from a JSON object: name, status_message, public, extra, build and project. |
Test Info |
tb:session-details |
Returns an object describing the running session: sessionId, testId, name, build, status (passed, failed or unknown), statusMessage, browserName, browserVersion, platform, deviceName, realDevice, startTime and url (the test's page in the dashboard). It never contains your credentials. |
— |
tb:break |
Pauses the test at this point. Open the test in your dashboard to take over the session with mouse and keyboard. | Break test |
tb:visual.snapshot=...tb:visual.baseline=...
|
Takes a visual snapshot and compares it with the baseline, or sets a new baseline. | Visual testing with Selenium, with Appium |
Browser and device commands
These commands act on the machine or device that runs your test, so each one works on some platforms only. Yes means the command works there; on the other platforms it returns an error or has no effect.
| Command | Arguments | Windows | macOS | Linux | Android emulator | iOS simulator | Real Android | Real iOS |
|---|---|---|---|---|---|---|---|---|
tb:throttle
Network throttling Notes |
'3G' or { downloadSpeed, uploadSpeed, latency, loss }
|
Yes | Yes | Yes | Yes | Yes | Yes | Yes |
tb:geo
Geolocation Notes |
{ code: 'DE' } |
Yes | Yes | Yes | Yes | Yes | Yes | Yes |
tb:locale
Localization Notes |
{ locale: 'fr', country: 'FR' } |
— | — | — | Yes | — | Yes | — |
tb:setTimezone
Device timezone Notes |
{ timezone: 'America/New_York' } |
— | — | — | — | — | Yes | Yes |
tb:restartApp
Notes |
none | — | — | — | Yes | Yes | Yes | Yes |
tb:killApp
Notes |
none | — | — | — | Yes | Yes | Yes | Yes |
tb:homeScreen
Notes |
none | — | — | — | Yes | Yes | Yes | Yes |
tb:talkBack
Screen readers Notes |
{ enabled: true } or { enabled: false }
|
— | — | — | Yes | — | Yes | — |
tb:voiceOverStart
Screen readers Notes |
none | Yes | Yes | — | Yes | — | Yes | — |
tb:a11ySettings
Notes |
{ fontScale, displaySize, boldText, highContrastText, animations } |
— | — | — | Yes | — | Yes | — |
tb:emulatorControls
Notes |
{ batteryLevel, charging, signal, mobileData, microphone, fingerprint } |
— | — | — | Yes | — | — | — |
tb:intercept
Network interception Notes |
interception rules | Yes | Yes | Yes | — | — | — | — |
tb:network
Network logs Notes |
none | Yes | Yes | Yes | — | — | — | — |
tb:performance
Performance metrics Notes |
none | Yes | Yes | Yes | — | — | — | — |
tb:accessibility
Accessibility testing Notes |
none | Yes | Yes | Yes | — | — | — | — |
tb:fileExists
File downloads Notes |
{ fileName: 'report.pdf' } |
Yes | Yes | Yes | — | — | — | — |
tb:autoit
AutoIt |
AutoIt script | Yes | — | — | — | — | — | — |
tb:osascript
AppleScript |
{ script, timeout } |
— | Yes | — | — | — | — | — |
tb:getExtensionId
Browser extensions Notes |
none | — | Yes | — | — | — | — | — |
tb:swipeDown
Notes |
none | — | — | — | Yes | — | — | — |
Notes per command
tb:throttle
Pass a preset name (airplane, edge, 3G or 4G) or your own speeds. disable removes the throttle again. See Network throttling for the presets and examples.
tb:geo
Routes the session's traffic through a location in the country you pass, as a two-letter uppercase country code. Use a code from the geolocation list. This changes the IP address websites see; to change the GPS position of a device, use your framework's location command instead.
tb:locale
Changes the language and region of an Android emulator or real Android device while the test runs. To start a test in a language on any platform, use the capabilities on Localization testing on iOS and Android.
tb:setTimezone
Changes the time zone of a real device while the test runs. Pass an IANA time zone name such as America/New_York or Europe/Paris. The time zone is reset after the session. To start a test in a time zone, use the timeZone capability.
tb:restartApp, tb:killApp and tb:homeScreen
tb:killApp stops the app under test, tb:restartApp stops it and starts it again, and tb:homeScreen goes to the device's home screen and leaves the app running in the background. They act on the app you started the session with.
tb:talkBack, tb:voiceOverStart and tb:voiceOverStop
- On Android emulators and real Android devices, all three commands turn TalkBack on or off. On emulators, TalkBack is available from Android 14 (API 34).
- On Windows,
tb:voiceOverStartstarts the NVDA screen reader; on macOS it starts VoiceOver. - In an iOS simulator session these commands do not control VoiceOver inside the simulator. Real iOS devices do not support them.
See Screen Reader Testing for how the screen readers behave on TestingBot devices.
tb:a11ySettings
Changes the display and accessibility settings of an Android emulator or real Android device. Pass any of these keys; pass no argument to only read the current settings. The command answers with the settings after the change, and the device gets its own settings back at the end of the session.
-
fontScale:small,default,large,larger,largestorhuge -
displaySize:small,default,large,largerorlargest -
boldText:trueorfalse(Android 12 and newer) -
highContrastText:trueorfalse -
animations:falseturns off window, transition and animator animations
await driver.executeScript('tb:a11ySettings', [{ fontScale: 'largest', boldText: true }]);
tb:emulatorControls
Changes the simulated hardware of an Android emulator. Pass any of these keys; pass no argument to only read the current state. The command answers with the state after the change.
-
batteryLevel: 0 to 100 -
charging:trueorfalse -
signal:none,poor,moderate,goodorgreat -
mobileData:trueorfalse. The emulator stays online over Wi-Fi; this changes what apps see for the cellular network. -
microphone:falseblocks microphone access for every app (Android 12 and newer) -
fingerprint:matchtouches the sensor with an enrolled finger,nomatchwith an unknown one. Set a screen lock and enroll a fingerprint first.
await driver.executeScript('tb:emulatorControls', [{ batteryLevel: 15, charging: false, signal: 'poor' }]);
tb:intercept, tb:network and tb:performance
These need the debugging capability set to true, and work with Chrome and Microsoft Edge on desktop. Without it, they answer with a message that asks you to add the capability.
tb:accessibility
Runs an accessibility scan (axe-core) on the page that is open in the browser and returns the results. Frames inside the page are not scanned.
tb:fileExists, tb:fileProperties and tb:fileContent
Check a file the browser downloaded during the test: whether it exists, its size, timestamps and MD5 checksum, or its content. See Test file downloads.
tb:getExtensionId
Returns the identifier of the extension you loaded with the load-extension capability. It works for Safari extensions on macOS.
tb:swipeDown
Performs one swipe gesture on an Android emulator to scroll the page, for example to hide the browser's address bar.