Skip to main content

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=passed
tb: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
tb:voiceOverStop

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
tb:fileProperties
tb:fileContent

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:voiceOverStart starts 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, largest or huge
  • displaySize: small, default, large, larger or largest
  • boldText: true or false (Android 12 and newer)
  • highContrastText: true or false
  • animations: false turns 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: true or false
  • signal: none, poor, moderate, good or great
  • mobileData: true or false. The emulator stays online over Wi-Fi; this changes what apps see for the cellular network.
  • microphone: false blocks microphone access for every app (Android 12 and newer)
  • fingerprint: match touches the sensor with an enrolled finger, nomatch with 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.

Was this page helpful?
Last updated