Skip to main content

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.

  • BROWSERSTACK_LOCAL_BINARY: override the delivered executable path.

  • BROWSERSTACK_LOCAL_BUNDLE_DIR or -Dds.browserstack.local.bundleDir: override the bundled folder.

  • BROWSERSTACK_LOCAL_CACHE_DIR or -Dds.browserstack.local.cacheDir: choose the managed cache.

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.