WebDesigner: BrowserStack setup, configuration, and usage

Run DesignerScript against BrowserStack cloud desktop browsers and real mobile browsers from WebDesigner or AIQ. Setup, configuration, execution evidence and troubleshooting. Reviewed 16 Nov 2026.

Overview and quick start

AIQ New Functionality · WebDesigner – New Functionality

SETUP AND OPERATIONS GUIDE   Reviewed 16 Nov 2026

Run DesignerScript against BrowserStack cloud desktop browsers and real mobile browsers from WebDesigner or AIQ. This guide takes you from obtaining account details to configuring profiles, running a test, finding its evidence, and diagnosing failures.

Scope: this is the new WebDesigner/DSServer integration for testing websites, including websites in mobile browsers. Native mobile applications and the older Mobile Designer/App Automate workflow have separate setup. The behavior below requires matching BrowserStack-enabled AIQ, frontend, shared-library and DSServer builds.

Current acceptance boundary: selected desktop and mobile playback flows have passed. Accessibility scans and final report logging have been verified on Windows 11 Chrome. Distributed AIQ scenarios, the newest starter targets, and mobile accessibility remain unverified. The Android full-page snapshot defect, where the top screen repeated down the image, was fixed and verified on a Pixel 9 / Android 15 on 16 Nov 2026. See the verification matrix before planning coverage.

Quick start

  1. Sign in to BrowserStack with the account your team will use. Confirm Automate entitlement, the required desktop/mobile targets, and available parallel capacity.

  2. Get the account’s Username and Access Key from Account & Profile. Keep the access key private.

  3. In AIQ, open Admin Options → Services → BrowserStack as an administrator or owner.

  4. Enter the credentials, keep the Local base path at ./browserstack-local, and begin with one concurrent session per node.

  5. Load/refresh the catalog, enable a desktop Chrome profile, choose a stable project name, and decide whether this account should run accessibility scans.

  6. Enable the integration and click Save settings. For WebDesigner on your own workstation, start it and click Apply to My Local Webdesigner.

  7. Refresh the browser selector, choose BrowserStack-Chrome-Latest-Windows11, run a short normal-mode test, and stop it.

  8. Confirm the session has ended in BrowserStack Automate and look for BrowserStack remote stop acknowledged in the DS operational log.

A successful first run proves: the profile is available, the cloud browser reaches the application, DesignerScript actions execute, and the cloud session closes. If accessibility is enabled, also confirm scans were saved and inspect the final Accessibility report.

How the integration works

Stage What happens What you control
Configure AIQ stores the account and enabled profiles. Each receiving DSServer saves its configuration to its own active global.json. Credentials, enabled profiles, per-node concurrency, project name and accessibility settings.
Start DSServer checks availability and capacity, creates a session-owned proxy route and starts BrowserStack Local, then allocates one cloud browser session. Choose a saved BrowserStack profile. Normal mode is required.
Run Cloud web traffic passes through BrowserStack Local and the owning DS proxy. Existing DesignerScript injection and playback drive the application. Use the script’s normal navigation, accessors, assertions and waits within the target’s supported scope.
Finish DSServer finalizes accessibility when enabled, deletes the cloud session, stops its Local tunnel and releases the node slot. Final accessibility counts are fetched in the background. Stop interactive sessions; check cleanup and the final report.

Traffic path: BrowserStack browser → BrowserStack Local tunnel → session-owned DSServer proxy → application under test. The execution machine must be able to reach the application. Local is part of this integration even for publicly reachable websites.

Each run receives a unique name, AIQ-<yyyyMMddHHmmss>-<DS session>-<32-character id>, used for its BrowserStack session and Local tunnel. The timestamp uses the execution node's local time. The build name follows the Build name setting: the run's unique name (default), one build per day AIQ-YYYY-MM-DD, or always AIQ-Executions. An optional Build name suffix is added to any of them after a dash, for example AIQ-2026-11-17-Avantor. Retain the full unique session name when correlating evidence; in a shared build, find a run by its session name.

Target Control connection Practical consequence
Desktop Chrome / Edge CDP when available; otherwise WebDriver. Native protocol features depend on attachment succeeding.
Desktop Firefox BiDi when available; otherwise WebDriver. Do not infer full local-Firefox feature parity.
Desktop Safari WebDriver. Uses HTTP browser-message transport and provider network logging for HTTPS trust.
Android Chrome WebDriver through Appium. No attached CDP session; full-page snapshots are stitched, which takes longer than on desktop Chrome.
iPhone / iPad Safari WebDriver through Appium. Uses buffered WebSocket browser messages and provider network logging for HTTPS trust.

Set up BrowserStack and configure AIQ

Set up BrowserStack and collect the required data

Prepare the account

  1. Open BrowserStack sign-in and use the intended team account or organization membership.

  2. Confirm that the account can use Automate for the browser/device combinations you need. This integration launches web browsers; it does not require uploading an IPA or APK.

  3. Open Account & Profile and find the automation Username and Access Key. BrowserStack also documents these under Automate settings. Copy the displayed automation username exactly; do not substitute an email address or account password.

  4. Check the account’s plan and current use before increasing parallel execution. AIQ’s account check and BrowserStack’s Plan API documentation explain the available parallel capacity.

  5. For automated accessibility, confirm the account has the required Accessibility entitlement. BrowserStack’s overview states paid-plan availability; framework onboarding also mentions trials, so verify the entitlement actually enabled for your account.

Data you need Where to get it Where it goes
Automation username BrowserStack Account & Profile / Automate settings. AIQ BrowserStack username; direct configuration: browserStack.username.
Access key The same BrowserStack account settings. AIQ access-key field; direct configuration: browserStack.accessKey. Never place it in a URL, a scenario or this page.
Browser, version, OS and device tuple AIQ Load / refresh catalog; BrowserStack’s browser/device selection guide and browser-list API. An enabled profile’s target. Use exact catalog values.
Parallel capacity and current usage AIQ account check / BrowserStack Automate plan. Choose maxSessions per DSServer, with enough account capacity for all nodes together.
Project name A stable team-chosen label, for example CustomerPortal-QA. AIQ Project name / defaults.projectName. It groups reports and helps create direct report links.
Local binary path The matching Appvance installation. Normally ./browserstack-local; it is a path on each execution machine, not a value from the BrowserStack account.
Application URL and test data The application/environment owner. Your DesignerScript and existing test-data configuration. BrowserStack does not supply application accounts or business data.

BrowserStack’s capabilities reference documents provider settings. AIQ/DSServer uses its own validated configuration schema; do not paste a complete SDK YAML or raw capability object into the AIQ settings.

Credential changes: after rotating a BrowserStack key, enter the replacement in AIQ, save, and apply it to standalone workstations. Scenario nodes receive current settings during launch. Saving the AIQ key field blank preserves the saved key; it does not clear it.

Configure AIQ and your WebDesigner

Save the central configuration

  1. Sign in to AIQ as an administrator or owner.

  2. Open Admin Options → Services → BrowserStack. The route is /UI/admin-options.html#services; use your AIQ server’s origin.

  3. Enter the BrowserStack username and access key. The saved key is redacted on readback.

  4. Leave BrowserStack Local base path as ./browserstack-local unless the node installation uses another location.

  5. Set maximum concurrent sessions. The default is 1 per node. Raising it does not increase the BrowserStack account’s quota.

  6. Choose the Build name: Generated build name each run (default), One build name per day (AIQ-YYYY-MM-DD) or Static build name (AIQ-Executions). Optionally enter a Build name suffix, added to the end after a dash. It allows up to 64 letters, digits, dots, underscores or dashes. The field shows the resulting name, and Save settings stays disabled while the suffix is invalid. Session names always stay unique per run.

  7. Click Load / refresh catalog. Search by browser, version, OS or device; results are paged in groups of 25. Add the combinations your team needs.

  8. Use stable, unique profile names beginning with BrowserStack-. Enable the profiles that should appear in selectors.

  9. Review Accessibility testing. It is on by default, with WCAG 2.1 AA. Set a stable project name, or turn accessibility off when it is not wanted or the account lacks entitlement.

  10. Turn on the integration and click Save settings. Account and catalog checks do not create cloud browser sessions.

Apply to the correct machine

Action Destination What success means
Save settings AIQ central settings, followed by a best-effort HTTP apply to the AIQ server’s own localhost. The settings were saved. Save can succeed while that server’s WebDesigner is stopped.
Apply to My Local Webdesigner A direct request from your browser to http://localhost:9090 on your workstation. Your running local DSServer accepted the saved revision. Start WebDesigner first; no open design session or WebSocket is required.
AIQ scenario launch The selected execution node, using the private node-configuration channel. The node applies the expected revision and verifies the selected profile before allocating a browser.

After local Apply succeeds, reopen or refresh WebDesigner’s browser selector. Desktop profiles appear under BrowserStack; device profiles appear under BrowserStack mobile. Settings persist in the receiving DSServer’s active global.json.

Remote AIQ server: localhost in the Apply button means the computer running your browser, not the AIQ server. Browser private-network, local-network or mixed-content policies can block this call. Use your organization’s approved browser/site permissions; the page reports Your local Webdesigner is unreachable. for connection, timeout or browser-policy failures.

Maintain profiles safely

Choose browsers and devices

The following twelve profiles are present in the reviewed source defaults after the 16 Nov 2026 catalog refresh. This is a source snapshot, not a promise that every deployed AIQ installation already contains the refresh or that every target has passed playback. Refresh the account catalog before adding targets.

Profile name Configured target Acceptance note
BrowserStack-Chrome-Latest-Windows11 Chrome latest · Windows 11 Playback and accessibility verified.
BrowserStack-Edge-Latest-Windows11 Edge latest · Windows 11 Saved-script playback verified; DS skips accessibility.
BrowserStack-Firefox-Latest-Windows11 Firefox latest · Windows 11 Playback verified; DS skips accessibility.
BrowserStack-Chrome-Latest-Windows10 Chrome latest · Windows 10 Not played in the recorded checks.
BrowserStack-Chrome-Latest-macOS-GoldenGate Chrome latest · macOS Golden Gate New target; playback pending.
BrowserStack-Safari-Latest-macOS-GoldenGate Safari latest · macOS Golden Gate New target; playback pending.
BrowserStack-Safari-Latest-macOS-Tahoe Safari latest · macOS Tahoe New target; playback pending.
BrowserStack-Chrome-Pixel11-Android17 Google Pixel 11 · Android 17.0 New target; playback and accessibility pending.
BrowserStack-Chrome-GalaxyS26-Android16 Samsung Galaxy S26 · Android 16.0 New target; playback and accessibility pending.
BrowserStack-Safari-iPhone18Pro-iOS27 iPhone 18 Pro · iOS 27 New target; playback and accessibility pending.
BrowserStack-Safari-iPhone16-iOS18 iPhone 16 · iOS 18 Playback verified on 18.5/18.6; accessibility pending.
BrowserStack-Safari-iPadAir13-iOS26 iPad Air 13 (2025) · iPadOS 26 New OS target; playback and accessibility pending.

Desktop profiles can use latest; reproducible release testing should select an explicit catalog version when required. Mobile profiles select an exact device and OS combination. Catalog availability, account entitlement, DSServer feature support, and verified application playback are separate checks.

Run tests and access private networks

Run tests and verify the first session

Interactive WebDesigner and saved scripts

  1. Apply the configuration to the workstation that runs DSServer, then refresh its browser list.

  2. Choose the enabled BrowserStack-… profile in the normal browser selector.

  3. Incognito does not matter. Every BrowserStack session already starts with a fresh, isolated profile, so DSServer ignores the incognito setting for BrowserStack profiles (since 17 Nov 2026; older builds refused it with BROWSERSTACK_UNSUPPORTED: explicit incognito mode). Selecting a browser in WebDesigner only selects it; it changes no settings.

  4. Begin with a short script: navigate to the application, wait for a known element, perform a representative click or form entry, and assert the expected page state.

  5. Stop the interactive session when finished. Saved-script lifetime follows the existing script owner; verify cleanup rather than assuming a completed action closes every session.

  6. Find the matching build/session in Automate using the complete AIQ-… run name. Confirm the target and ended state, and compare application assertions with the DS playback result.

  7. If the browser does not start, the run fails with the reason. WebDesigner's execution log shows Could not start <browser>: <reason>, for example BROWSERSTACK_REFUSED: Automate testing time expired., and the page returns to idle instead of staying in "loading". Saved scripts and AIQ scenarios get the same message as the DSClient start error.

AIQ scenarios

In the scenario editor select the profile as the testcase Browser or Override Browser. AIQ delivers the current private provider configuration separately to the execution node. Credentials are not serialized into the scenario. The launch bridge maps its default incognito preference to normal cloud startup.

Install matching components on every node, confirm application/VPN reachability from those nodes, and run a short scenario on each intended node before scheduling a larger workload. Distributed BrowserStack scenario acceptance remains pending in the reviewed evidence.

First-run acceptance checklist

The default provider idle timeout is 90 seconds. Long pauses can end the browser. A session-start request is not automatically retried: after an uncertain allocation DSServer attempts to identify and clean up only the exact owned session. Diagnose the original run before starting another.

BrowserStack Local and private network access

DSServer starts and stops a private BrowserStack Local process for each cloud run, using the run’s unique identifier and assigned DS proxy. Keep this managed path for Appvance execution. The generic BrowserStack instructions for manually running a Local binary are useful for understanding networking, but do not replace the session-owned DS tunnel.

Requirement How to prepare
Application access From the actual DSServer machine, verify the application URL, DNS, VPN and required authentication routes. A VPN available only on a developer laptop does not give a separate execution node access.
Outbound provider access Allow HTTPS/WSS to BrowserStack, normally outbound 443. BrowserStack’s firewall/VPN guide specifies *.browserstack.com on 443. Coordinate allowlisting with the network team.
Session and account services Reach hub-cloud.browserstack.com and api.browserstack.com.
Local updates Reach local-downloads.browserstack.com; verify the DSServer account can write its managed cache/runtime locations.
Accessibility services Reach collector-observability.browserstack.com and api-accessibility.browserstack.com, or the configured regional report API.
Complete installation Keep the release-matched browserstack-local folder beside the DSServer JAR. Relative paths resolve from that JAR folder.

The bundled host choices are Windows x64, macOS x64/ARM64, Linux x64/x86/ARM64 and Linux musl x64. DSServer chooses the binary for the execution machine, independently of the cloud browser’s OS. Windows execution is recorded; foreign binaries were downloaded and format/hash checked, not executed in the cited provisioning checks.

Managed startup checks official downloads and can reuse a verified cached/bundled copy if an update fails. Each run uses its own writable runtime copy. The normal cache is ~/.appvance/browserstack-local. See BrowserStack’s Local downloads for provider distributions.

Safari HTTPS: keep the supplied Safari/iOS networkLogs=true policy and captureNetworkContent=false. The provider’s network-log proxy is part of the measured certificate-trust solution. Response-body capture is disabled, but network metadata may still be recorded. acceptInsecureCerts alone did not establish trust in the recorded iOS checks.

Accessibility testing and execution evidence

Enable Send BrowserStack accessibility testing with each session in AIQ, choose the standard and issue categories, and set a stable project name. BrowserStack’s automated accessibility overview describes its SDK/reporting model; the Appvance controls below govern the integrated implementation.

SettingDefaultEffect

Accessibility enabled

On

Runs registration/scans only when the DS target gate permits them and BrowserStack accepts registration. Off means no accessibility registration, scan or report.

Accessibility standard

WCAG 2.1 AA

WCAG 2.0 / 2.1 / 2.2 at A, AA or AAA; or RGAA. Choose the standard required by the project.

Issues needing review / experimental / advanced

On / on / on

Select which additional issue categories to include.

Best-practice recommendations

Off

Optional advisory category.

Scan automatically after page changes

On

Despite this UI label, DS currently scans 

before

 relevant page-changing playback actions and once at stop. With automatic scanning off, only the final scan runs.

Project name

Blank

Keep a stable nonblank name to group reports and enable direct report links. Blank can lead to a dashboard-only link.

Target eligibility versus verified scans

TargetCurrent DSServer eligibilityEvidence boundary

Chrome 100+ on Windows/macOS

Eligible.

Windows 11 Chrome verified; other combinations still need acceptance.

Safari on macOS Sequoia, Tahoe or Golden Gate

Eligible. Scanned with BrowserStack's in-page scanner; no accessibility capability is sent (since 17 Nov 2026).

Golden Gate verified live through DSServer on 17 Nov 2026: 2 scans, results saved, processed report (94 issues, score 49). Tahoe and Sequoia not yet run with the current build.

Chrome on Android 15+

Eligible in code.

DS live accessibility acceptance pending, including Android 17 starter.

Safari on iOS 18+

Eligible in code.

DS live accessibility acceptance pending.

Edge / Firefox / older targets

Skipped by DS.

A functional cloud run can still proceed without scans.

Provider support varies by framework. BrowserStack now documents Edge for selected SDK frameworks. Its TestNG guide and Playwright guide also differ on iOS and Android details. The table above describes DSServer’s current gate, not universal BrowserStack certification. A catalog entry or accepted capability does not prove scans ran.

Compare the current TestNG support matrix, Playwright support matrix and provider troubleshooting guide when investigating a target or entitlement issue.

What happens during a run

DSServer registers the build, obtains provider scanner data, attaches the required token to the cloud session, reports a test run, scans during playback, and saves/finalizes at stop. Merely sending accessibility=true produced no scans in earlier checks; the current implementation performs the additional SDK lifecycle steps.

These steps use BrowserStack’s internal SDK protocol and can change on the provider side. Failures are best effort and logged; they do not automatically fail the DesignerScript. Scanning adds latency to affected actions, so measure representative workflows before increasing concurrency.

Desktop Safari (since 17 Nov 2026**).** BrowserStack's scan script normally waits for BrowserStack's browser extension to appear in the page. For Safari, the accessibility capability made BrowserStack set up its "Accessibility Toolkit Headless" Safari extension. Its setup window could stop Safari from starting ("timed out while connecting to a Safari instance"), and the extension never reached the page, so every earlier Safari scan answered "Scanner is not ready on the page after multiple retries." DSServer now sends no accessibility capability for desktop Safari and runs the script's in-page mode, which phones also use: it loads BrowserStack's scan engine into the page itself. That mode runs no advanced rules and depends on the account's mobile-scanning switch. A scan reply that says it did not scan now counts as a failed scan, and its message is logged.

Final playback step. The collectBrowserStackData step, which logged the run's BrowserStack data at the end of a playback, was added on 16 Nov 2026 and turned off on 17 Nov 2026, because it did not work in scenario runs. Results are still saved when the session stops, and the final report is still logged by DSServer.

Open the final report

  1. Stop the test so results are saved and the build can finish processing.
  2. Follow the report=… link in the DS operational log, or open Accessibility → Automated Tests.
  3. Choose the configured project and the exact AIQ-… build. Review severity counts, score, pages, components and needs-review items.
  4. Use the BrowserStack accessibility final report log line for processed counts. The preliminary summary is not the final result.
  5. If the final report is delayed, allow processing time. DS starts checking after 30 seconds, repeats every 30 seconds and gives up after 10 minutes without keeping the browser session open.

Two dashboard pitfalls: the Automate build’s own Accessibility tab still showed “not enabled” in the recorded integrated runs; the actual report was in the separate Accessibility product. Test health can appear red because DS currently reports the test outcome as unknown; pass/fail reporting is deferred. Consult the DesignerScript result and final accessibility report separately.

In one recorded verification, the preliminary count was 3 issues; the processed report was 40 issues (2 critical, 11 serious, 27 moderate), score 74, logged after 60 seconds. These are historical verification results, not expected counts for your application.

Find execution data and logs

InformationWhere to find itHow to interpret it

Cloud build and browser session

BrowserStack Automate dashboard, matched by the full AIQ-… name.

Confirm the requested target, lifecycle and provider diagnostics. An ended session is not proof all application assertions passed.

Application pass/fail

WebDesigner playback output or AIQ execution result.

This is the application-test outcome; the provider’s accessibility test-health status can differ.

Accessibility findings

Accessibility → Automated Tests and the DS final report line.

Use processed counts and the report details, not the preliminary count.

Node operational log

Installed: <installation>/NetworkProxy/OutputLogs/ds3output0.txt. Development: distribution/OutputLogs/ds3output0.txt.

Rotates to ds3output1.txt. Configuration lines use [browser.configuration]; run lines use [browser.lifecycle].

Current redacted node configuration

GET /ds/dyn/platform/getBrowserStackConfiguration on the intended DSServer.

Shows configuration and availability without credentials.

Actual running capabilities

GET /ds/dyn/platform/getBrowserStackCapabilities?session=<DS-session>.

Returns provider session ID, browser/OS, selected connection and accessibility state.

Available target catalog / plan

AIQ Services BrowserStack account/catalog tools; provider browser-list and Plan APIs.

Catalog and account reads do not allocate browser sessions.

Operational log messages to recognize

Message prefixMeaning

BrowserStack configuration rejected; local browsers remain available

Invalid saved configuration; inspect fields before retrying.

Browser configuration loaded / Skipping browser with invalid configuration

Per-profile loading result.

BrowserStack accessibility build registered

Registration succeeded; includes the report build ID.

BrowserStack accessibility skipped / was not enabled by BrowserStack / build registration failed

No scans for that run; the message identifies the gate or provider failure.

BrowserStack accessibility scan failed; later failures are counted at finish

First scan failure. reason= is BrowserStack's message when the scanner answered without scanning, for example Scanner is not ready on the page after multiple retries.; cause= is a call failure. Inspect finish counts for the aggregate.

BrowserStack accessibility preliminary summary (final counts in report)

In-session summary at stop; not the processed report.

BrowserStack accessibility finished

Includes scans, failedScans and saved=true/false.

BrowserStack accessibility final report

Processed issues/severities, score, pages, components, needs-review, wait duration and report link.

BrowserStack accessibility final report not ready / is not readable with this account / report processing did not complete

Processing deadline, authorization failure or provider failure. Follow the report link.

BrowserStack remote stop acknowledged

Provider session deletion acknowledged.

BrowserStack remote stop could not be confirmed

Inspect that exact provider session in the dashboard.

BrowserStack uncertain allocation

Start response was uncertain; owned-session reconciliation/cleanup is attempted.

Failed to start browser session (operational log) / Could not start <browser>: <reason> (execution log)

The browser did not start; the run is marked failed with BrowserStack's reason, for example BROWSERSTACK_REFUSED: ….

When escalating, include the selected profile, full run name, DS/provider session IDs, actual browser/OS, relevant sanitized log lines, action that failed, and whether cleanup was confirmed. Keep access keys, tokens, private URLs containing credentials, and sensitive application data out of shared evidence.

Advanced configuration reference

Advanced configuration reference

Most administrators should use AIQ. The following reference is for standalone nodes and integration tooling. DSServer validates known keys and keeps its existing ownership boundaries; generic BrowserStack capabilities are not arbitrary pass-through settings.

Standalone global.json example and editing

procedure

  1. Stop the affected DSServer with its normal service/launcher controls and back up the active configuration.

  2. Locate <installation>/NetworkProxy/config/global.json (development run: distribution/config/global.json).

  3. Merge the root browserStack object alongside existing root sections. Preserve all other configuration. The example deliberately disables accessibility for an initial functional smoke test; enable it when the account and target are ready.

  4. Replace the credential placeholders privately. The profiles array replaces the existing list; these names match known starter profiles whose internal fields are filled by the loader.

  5. Start DSServer, inspect configuration logs, and verify the profile list and one short run.

{

"browserStack": {

"enabled": true,

"username": "<BROWSERSTACK_USERNAME>",

"accessKey": "<BROWSERSTACK_ACCESS_KEY>",

"localBinary": "./browserstack-local",

"maxSessions": 1,

"defaults": {

"projectName": "CustomerPortal-QA",

"accessibility": false

},

"profiles": [

{

"name": "BrowserStack-Chrome-Latest-Windows11",

"enabled": true,

"target": {

"browser": "chrome",

"browser_version": "latest",

"os": "Windows",

"os_version": "11"

}

},

{

"name": "BrowserStack-Safari-iPhone16-iOS18",

"enabled": true,

"target": {

"browser": "iphone",

"os": "ios",

"os_version": "18",

"device": "iPhone 16",

"real_mobile": true

}

}

]

}

}

The active file contains the access key in plain text. Restrict filesystem access and keep it out of source control, support bundles and shared folders. Shipped templates contain blank credentials. For custom targets, add through AIQ’s catalog or preserve the complete profile structure described below.

Account, endpoints and browser policy

Setting Default Meaning
enabled false Opt-in integration switch.
username, accessKey Blank BrowserStack account credentials.
localBinary ./browserstack-local Bundled directory or explicit executable path.
maxSessions 1 Per-node cloud-session limit.
revision local AIQ sets a new saved revision; a running session retains its launch configuration.
endpoints.webdriver https://hub-cloud.browserstack.com/wd/hub Session creation and commands.
endpoints.api https://api.browserstack.com Plan validation and uncertain-allocation reconciliation.
endpoints.testhub https://collector-observability.browserstack.com Accessibility registration/events/finalization.
endpoints.accessibilityApi https://api-accessibility.browserstack.com Final report reads. Use the account’s documented regional endpoint if region restrictions apply.

Endpoints must use HTTPS and contain no URL credentials; only localhost test endpoints may use HTTP.

Policy precedence: defaults → matching familyDefaults (Chromium, Firefox, Safari) → iosDefaults for real iOS → the profile’s overrides. Later layers override earlier ones.

Policy key Default Meaning
seleniumVersion 4.45.0 Requested provider Selenium version.
idleTimeoutSeconds 90 Provider idle timeout.
nativeProtocol auto auto, webdriver, cdp or bidi. Explicit CDP/BiDi fails startup if attachment is unavailable.
acceptInsecureCerts true Certificate policy; insufficient by itself for the measured Safari trust path.
networkLogs False; true for Safari/iOS Provider network proxy/logging used by the Safari HTTPS path.
captureNetworkContent false Response-body capture.
projectName Blank Stable BrowserStack grouping/report project.
buildNameMode perRun Build naming: perRun (unique per run), perDay (AIQ-YYYY-MM-DD, node-local date) or static (AIQ-Executions). AIQ's Build name sets it.
buildNameSuffix Blank Added after a dash to every build name in any mode. Up to 64 letters, digits, ., _ or -; other text rejects the configuration. Blank adds nothing and clears an earlier suffix. AIQ's Build name suffix (optional) sets it (17 Nov 2026).
accessibility true Enable integrated scans when eligible.
accessibilityOptions WCAG 2.1 AA; auto scanning true wcagVersion: wcag2a, wcag2aa, wcag2aaa, wcag21a, wcag21aa, wcag21aaa, wcag22a, wcag22aa, wcag22aaa; or rgaaVersion: "rgaa". Issue-type booleans: needsReview, experimental, advanced, bestPractice.
Advanced accessibility scope Unset includeTagsInTestingScope and excludeTagsInTestingScope are accepted lists. There is no AIQ field for them; end-to-end tag-based selection was not verified in this documentation review.

Profile schema, timeouts and Local overrides

Profile field Rule
name Unique; begins BrowserStack-; remaining characters use letters, digits, dots, underscores or hyphens. Preserve referenced names.
enabled Controls availability in selectors.
target Browser, OS and OS version required; desktop also needs browser version. Real mobile needs device and real_mobile=true. Use exact catalog values.
ManagerClass com.appvance.platform.browserstack.BrowserStackBrowserManager.
browserFamily, groupName, isMobile Match the target and desktop/mobile grouping. No local executable or container-pool configuration.
options Keep session-routing: owned. Desktop Safari uses browser-message-transport: http.
overrides Per-profile browser policy, for example {"accessibility":false}.
Section Default values in milliseconds
timeouts connectMs=10000; createSessionMs=90000; commandMs=30000; deleteSessionMs=10000; localStartMs=60000; localStopMs=2000; accessibilityReportMs=240000 (used only by the final playback step, which is turned off).
polling inventoryMs=2000; healthMs=15000.
validation refreshIntervalMs=60000; connectTimeoutMs=1000; readTimeoutMs=1500.
localUpdates enabled=true; blank cacheDirectory; connectTimeoutMs=4000; readTimeoutMs=8000; downloadTimeoutMs=45000; lockTimeoutMs=60000; versionTimeoutMs=5000.

Configured timing values must be between 1 and 3,600,000 milliseconds. Accessibility final-report polling is fixed at 30-second intervals with a 10-minute deadline.

HTTP configuration for tools

Use POST /ds/dyn/platform/configureBrowserStack with form field configuration containing the JSON browserStack section itself. It merges, saves to the active file and applies immediately. Readback returns revision/profiles/availability without credentials.

Object merges do not delete omitted keys. Send explicit replacements to reset settings; a supplied profiles array replaces the saved array. To switch from RGAA back to WCAG, send rgaaVersion: "" with the chosen wcagVersion. Keep the credentials in the protected request body; never put them into URL parameters or command history. AIQ’s Apply button handles this transfer.

Verified behavior, troubleshooting and maintenance

These are the recorded implementation checks summarized by the current local guide. Version 3 of this page (17 Nov 2026) adds live checks run that day through DSServer against BrowserStack (desktop Safari accessibility on Golden Gate, start-failure reporting) and the unit tests listed below.

AreaRecorded status

Windows 11 Chrome

Live navigation, evaluation, accessor click, WebDriver/CDP and cleanup verified.

Windows 11 Firefox and Edge

Firefox interaction checks and Edge saved-script playback/cleanup verified.

macOS Safari

Playback verified on Sonoma. Golden Gate started and navigated through DSServer on 17 Nov 2026, with accessibility. Tahoe not played.

iPhone 16

Basic playback/cleanup verified on iOS 18.5 and 18.6.

Galaxy S24 Android 14 / iPad Air 13 iOS 18.6

Saved-script playback/cleanup verified. These are older targets than several refreshed defaults.

Accessibility

Windows 11 Chrome and macOS Golden Gate Safari (17 Nov 2026): scans, saved results and processed final report verified. Mobile and distributed-scenario accessibility pending.

Start failures, incognito, Build name suffix

17 Nov 2026: a refused start fails the run with BrowserStack's reason (verified live for Safari); incognito is ignored for BrowserStack; the Build name suffix is unit-tested and packaged but not yet saved from a running AIQ page.

AIQ settings

Local save/apply and earlier starter-list visibility verified. Actual save of the new accessibility fields in a running AIQ and production frontend acceptance remain pending.

Newest starter list

Source defaults and shared-library refresh recorded. New targets not played; AIQ had not been repackaged for that refresh.

Focused checks

17 Nov 2026: Accessibility 22/22, Configuration 18/19, Reconciliation 4/4, DSClient start failure 2/2, frontend BrowserStack module 24/24. Previously recorded: WebDriver connector 9/9, screenshot stitching 11/11, profile loader 4/4. The remaining Configuration check compares against an older AppvanceInterfaces JAR still on the DS test classpath.

Snapshots

Sizing correction packaged. Android repeated-screen defect fixed and verified live on 16 Nov 2026 (Pixel 9 / Android 15, vwr.com). Android pages no longer use ChromeDriver’s whole-page capture, which repeated the visible screen; they are stitched from screenshots that follow the visible area, also on pages wider than the screen. The snapshot showed the whole page, both edges and no repeats. iPhone/iPad bar cropping, ChromeDriver whole-page capture on non-Android sessions and the new targets remain unverified live.

Broad rollout

Full distributed scenarios, all versions/devices and long-duration production acceptance remain pending.

Feature limits to plan around

The in-page scanner used for phones and desktop Safari runs no advanced rules and loads its engine into the page from BrowserStack's asset host; a page whose Content Security Policy blocks that host cannot be scanned (not yet observed).

Troubleshooting

SymptomLikely causeAction

No BrowserStack profiles

Disabled integration/profile, missing/rejected credentials, failed Plan API check, or invalid configuration.

Inspect saved settings and configuration logs; reapply the correct account. Account checks refresh every 60 seconds by default.

Your local Webdesigner is unreachable.

Local process stopped, port 9090 unavailable, timeout or browser network policy.

Start local WebDesigner, verify the intended computer and retry Apply. Check approved browser local-network permissions if AIQ is remote.

BROWSERSTACK_UNSUPPORTED: explicit incognito mode

A DSServer build older than 17 Nov 2026, which refused incognito.

Update DSServer; current builds ignore incognito for BrowserStack.

Could not start <browser>: BROWSERSTACK_REFUSED: <reason>

BrowserStack answered the start without a session. "Automate testing time expired." means the account's Automate minutes are used up.

Act on BrowserStack's reason: add Automate time, check the account, or pick another target.

Desktop Safari: … The session timed out while connecting to a Safari instance after about 3 minutes

A DSServer build older than 17 Nov 2026 sent the accessibility capability for desktop Safari; BrowserStack's "Accessibility Toolkit Headless" setup window kept Safari from connecting.

Update DSServer; current builds use the in-page scanner for desktop Safari.

scan failed … reason=Scanner is not ready on the page after multiple retries.

The scan waited for BrowserStack's browser extension, which was not in the page.

On desktop Safari, update DSServer. On desktop Chrome, check the session in BrowserStack's dashboard.

BROWSERSTACK_CAPACITY

Node limit reached.

Wait for cleanup or adjust maxSessions within the account’s total capacity.

BROWSERSTACK_UNAVAILABLE

Credentials/configuration became unavailable or changed.

Check account status and reapply the current AIQ revision.

BROWSERSTACK_LOCAL_UNAVAILABLE / BROWSERSTACK_LOCAL_PLATFORM_UNSUPPORTED

No verified usable binary for the node host.

Check the bundled folder, executable permissions and update access; review explicit overrides.

Local proxy tunnel timeout

Outbound tunnel blocked or execution-node network not ready.

Check outbound HTTPS/WSS, VPN/proxy rules and application reachability from that node.

BROWSERSTACK_PROTOCOL_UNAVAILABLE

Explicit CDP/BiDi required but unavailable.

Use auto when fallback is acceptable; avoid native-only actions on WebDriver-only targets.

BROWSERSTACK_TLS_TRUST_REQUIRED

Safari rejected the DS proxy certificate.

Restore the supplied Safari/iOS networkLogs policy and verify the target’s trust behavior.

Accessibility says not enabled

Wrong product tab, disabled setting, unsupported DS target, entitlement or registration failure.

Open Accessibility → Automated Tests; check skipped/registration messages and the target matrix.

Accessibility counts differ

Preliminary in-session summary compared with processed report.

Wait for the final-report line and use processed report counts.

Red accessibility test-health status

DS currently reports test outcome as unknown.

Use the functional playback result and accessibility findings separately.

Final report unreadable

Account access, regional API configuration or processing failure.

Follow the report link; inspect 401/403 or processing messages and the account’s region restrictions.

Android snapshot repeats the page top

A DSServer build older than the Android snapshot fix of 16 Nov 2026.

Update DSServer on that execution machine. Until then, do not accept the image as a complete page.

Method not found clearLastSnapshot

Older DSClient call not implemented by DSServer.

Current guide records that capture continues; diagnose actual image content separately.

Remote stop not confirmed

Provider deletion acknowledgement lost/failed.

Inspect only the matching run/session in Automate and confirm it has ended before allocating additional work.

References and maintenance

Provider references were checked on 16 Nov 2026, and BrowserStack's accessibility and Safari pages again on 17 Nov 2026. Catalogs, UI labels, plans and supported SDK matrices can change. Use AIQ's live catalog and the linked provider pages for current account-specific choices.

Implementation basis for maintainers

This page is a publication snapshot of branch IQ-18353-5313-imp-p1, including the reviewed working-tree changes. Source implementation is not a claim of deployment to every installation.

Repository / pathPurpose

DS: documentation/BrowserManager/reference/browserstack.md

Canonical current operator guide and links to dated verification records.

DS: documentation/BrowserManager/design/codex/browserstack-configuration-review.md

Configuration, accessibility lifecycle, final report evidence and refreshed starter-list status.

DS: documentation/BrowserManager/design/codex/browserstack-live-failure-corrections.md

Measured desktop/mobile playback and cleanup results.

DS: DSServer/src/main/resources/com/appvance/platform/browserstack/browserstack-defaults.json

Actual shipped settings/profile defaults reviewed for this page.

DS: DSServer/src/main/java/com/appvance/platform/browserstack/BrowserStackAccessibility.java

Target eligibility, scan lifecycle and final-report polling reviewed for this page.

frontend-BrowserStack: documentation/browserstack.md

UI labels, key handling, catalog behavior and frontend acceptance limits.

AIQ: documentation/BrowserStack/README.md and http-configuration-application.md

Central Save, workstation Apply and private scenario-node delivery.

Keep this page synchronized with both the DS human guide and its knowledge-base route. Preserve dated evidence and distinguish source changes, packaging, live verification and deployed behavior. The newer provider Edge support is intentionally distinguished from DSServer’s narrower accessibility gate.