Bridge Application

Devices

What the tested application runs on is decided by the device-uri of a run. Its scheme selects the device implementation; its query parameters configure it.

Scheme Device Use

bs://

BrowserStack (Appium / Selenium)

The real mobile app on a device in the BrowserStack device cloud, or the web client in a BrowserStack desktop browser.

http://, https://

Virtual device

The tested agent is another engine session — no user interface at all. The fastest option, and the one to use when testing dialogue rather than the app.

ws://, wss://

Link device

A real client (browser or mobile) that has opened a Promethist link page and connects over its /link WebSocket.

external://

External device

A physical device sitting in front of a webcam and microphone, with no remote control at all.

BrowserStack Device (bs://)

The URI host is the identifier of the application binary uploaded to BrowserStack; the parameters configure the session.

Parameter Default Meaning

deviceType

iOS

iOS, Android or Desktop. Decides whether an Appium mobile driver or a Selenium browser driver is used.

deviceName

iPhone 17

Device model to allocate (mobile only).

platformVersion

26.0

OS version of the device (mobile only).

appPackage

ai.promethist

Application package of the app under test.

os, osVersion

OS X, Tahoe

Desktop operating system and version (desktop only).

version

latest

Browser version (desktop only).

isInteractive

false

Enables BrowserStack interactive debugging, so a human can take over the session in the BrowserStack UI while it runs.

width, height

—

Window size; when both are given the session window is resized.

Under the hood the bridge connects to BrowserStack’s Appium hub and drives the session through WebDriver:

  • Android uses the UiAutomator2 automation, iOS uses XCUITest; a plain browser test uses the matching Selenium driver instead.

  • The app is installed from the BrowserStack-hosted binary, with alerts auto-accepted and permissions auto-granted, so a run does not stall on a system dialog.

  • Screenshots are taken through WebDriver and are what the tester sees each turn.

  • Taps and drags are W3C pointer actions — touch on mobile, mouse on desktop; scrolling uses Selenium’s scroll action.

  • Opening a URL is a deep link on Android, an app launch with the URL as argument on iOS, and a plain navigation in a browser.

  • At the end of the run the verdict is reported back to BrowserStack, so the session appears there as passed or failed with its reason.

Because provisioning a real device takes time, the start of a bs:// run is noticeably slower than the other device types.

Audio and the Relay

A BrowserStack device cannot receive injected audio directly. For those runs the bridge routes the tester’s audio through the relay service: the page under test connects to the relay, the bridge connects to the relay as its peer, and messages are forwarded between the two by relay ID. This is why the mobile and web-client configurations carry a relayUrl.

Outgoing realtime audio is paced so the application receives it at a natural speed rather than as one burst: text-only utterances are timed at roughly 50 ms per character, raw audio chunks are spread according to audioSpeed, and short silence frames keep the stream alive between utterances.

Virtual Device (http://, https://)

The URI is the engine to connect to, and the key query parameter is the pipeline key of the agent under test — for example https://eu.promethist.ai?key=agent:acme-support.

The bridge opens a second engine session for that agent and relays between the two sessions, so two agents converse with each other. It handles #ready, #intro, agent handover and image and multimodal elements. Because there is no device, screenshots are unavailable and the tester works from the conversation alone.

This is the only device type where the bridge owns the tested side’s connection too, which is why testedAgentTestMode can be set for it.

Link Device (ws://, wss://)

The URI points at a companion client page; the bridge connects to its /link WebSocket and exchanges realtime audio and UI state with it. Use it to test a real client that can open a link, without the device cloud.

width and height set the assumed view size (512×1024 by default).

External Device (external://)

For a physical device that cannot be automated at all. The bridge captures the microphone, detects speech by loudness, and triggers a device turn when the device falls silent. Calling open prints a QR code to the terminal so a person can scan it on the device.

Parameter Default Meaning

vision

none

webcam uses the host’s webcam as the device’s screen; otherwise there is no visual input.

touch

none

Touch injection is not implemented, so gestures from the tester are ignored.

silenceTimeout

2500

Milliseconds of silence that end the device’s turn.

Device Queries

deviceQueries is a list of additional query strings appended to the device URI, and each entry produces its own run. Combined with deviceCount this is how one configuration fans out into a matrix of runs — for example the same test against several agents or several device models.