Draft page
Access: Prod
#browserstack #selenium #appium #playwright #cypress

Migrate BrowserStack Automation to webmate

If your existing suite already runs on BrowserStack Automate or App Automate, you usually keep the test logic and replace the connection layer. The migration work is mostly about removing BrowserStack-specific configuration, keeping standard WebDriver or Appium capabilities, and adding the wm: capabilities that webmate needs.

What Changes First

  • Remove BrowserStack SDK wrappers or browserstack.yml-driven session setup from the execution path.
  • Point remote WebDriver or Appium traffic at the webmate Selenium endpoint.
  • Replace browserstack.* or bstack:options values with standard capabilities plus wm:apikey, wm:project, and any optional wm:* metadata.
  • Treat Playwright and Cypress as framework-specific adapters on top of the same remote infrastructure change.

Selenium or WebDriver Migration

Start from the minimal webmate equivalent of a BrowserStack remote browser session:

Keep browserName, browserVersion, and platformName. Remove BrowserStack-only capability blocks and migrate metadata such as build or session naming to wm:name, wm:tags, or wm:sessions when you need them.

Appium Migration

For App Automate suites, the same pattern applies: keep the Appium capabilities that describe the app and platform, but move device selection and authentication into the webmate capability model.

If you previously uploaded apps through BrowserStack-specific flows, move that part to the webmate app upload workflow described in Upload a Mobile App to webmate .

Playwright Migration

For Playwright, set the remote Selenium URL and pass webmate capabilities through the environment before you run the existing suite:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

export SELENIUM_REMOTE_URL="https://selenium.webmate.io/wd/hub"
export SELENIUM_REMOTE_CAPABILITIES='{
  "browserName": "chrome",
  "browserVersion": "126",
  "platformName": "WINDOWS_11_64",
  "wm:apikey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
  "wm:project": "7c4f09fd-xxx-xxx-xxx-xxx"
}'

npx playwright test

This keeps the Playwright test code unchanged and swaps only the remote execution target.

Cypress Migration

BrowserStack-specific Cypress setup usually bundles service configuration into the project. In webmate, Cypress uses webmate-cypressbridge as the browser binary plus a local .conf file:

1
2
3
4
5
6

user: "xxx@xxx.com"
apikey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx="
project: "7c4f09fd-xxx-xxx-xxx-xxx"
browser: chrome
version: 126
platform: WINDOWS_11_64

Then start Cypress with the bridge binary instead of with a BrowserStack service integration.

Helper: Translate a BrowserStack Capability Object

Use this helper when your project still builds a BrowserStack capability object in code and you want a quick first-pass rewrite:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

function browserStackToWebmate(input) {
  const caps = { ...input };
  delete caps['browserstack.user'];
  delete caps['browserstack.key'];
  delete caps['browserstack.local'];
  delete caps['browserstack.networkLogs'];
  delete caps['browserstack.console'];
  delete caps['bstack:options'];

  return {
    ...caps,
    'wm:apikey': process.env.WEBMATE_API_KEY,
    'wm:project': process.env.WEBMATE_PROJECT_ID,
  };
}

console.log(JSON.stringify(browserStackToWebmate(JSON.parse(process.argv[2])), null, 2));

Review the output before you commit it. The helper removes obvious BrowserStack-only keys, but it cannot decide which wm:model, wm:name, or wm:tags values you actually want.

Next Steps