# Set up BrowserStack and configure AIQ

## Set up BrowserStack and collect the required data

### Prepare the account

1.  Open [BrowserStack
    sign-in](https://www.browserstack.com/users/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](https://www.browserstack.com/accounts/profile/details) 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](https://www.browserstack.com/docs/automate/api-reference/selenium/plan)
    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](https://www.browserstack.com/docs/automate/selenium/select-browsers-and-devices) and [browser-list API](https://www.browserstack.com/docs/automate/api-reference/selenium/browser). | 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](https://www.browserstack.com/docs/automate/capabilities)
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

  - Only enabled, saved profiles appear for new selections. A disabled
    profile referenced by an existing scenario stays visible as
    unavailable; it is not silently replaced.

  - Do not rename a profile already used by saved scenarios. Add a new
    named profile when a distinct target/version is needed.

  - Fresh settings receive the starter list. Saved custom, disabled or
    deliberately empty lists are preserved; an upgrade does not reseed
    them.

  - Once accessibility settings are saved, every receiving node needs
    the updated DSServer. Older nodes reject the new policy keys.

## 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.