BrowserStack Cheat Sheet

Overview

BrowserStack is a cloud-based testing platform that provides access to real browsers and devices for manual and automated cross-browser testing. It enables developers and QA teams to test websites and web applications across thousands of browser-OS-device combinations without maintaining a local device lab. BrowserStack covers desktop browsers, mobile browsers, and native mobile apps.

The platform offers multiple products: Live (manual testing), Automate (Selenium/Cypress automation), App Live (manual mobile app testing), App Automate (Appium automation), Percy (visual testing), and Accessibility testing. It integrates with CI/CD tools like Jenkins, GitHub Actions, CircleCI, and Azure DevOps.

Installation

# BrowserStack CLI
npm install -g browserstack-cli

# Selenium WebDriver (Node.js)
npm install selenium-webdriver browserstack-local

# Cypress integration
npm install -D @browserstack/cypress-cli

# BrowserStack Local (tunnel for local testing)
# macOS
brew install browserstack/tap/browserstack-local

# Linux
wget https://www.browserstack.com/browserstack-local/BrowserStackLocal-linux-x64.zip
unzip BrowserStackLocal-linux-x64.zip
chmod +x BrowserStackLocal

BrowserStack Local (Tunnel)

# Start local tunnel
./BrowserStackLocal --key YOUR_ACCESS_KEY

# With options
./BrowserStackLocal --key YOUR_ACCESS_KEY \
  --local-identifier my-tunnel \
  --force-local \
  --verbose 3

# Force all traffic through tunnel
./BrowserStackLocal --key YOUR_ACCESS_KEY --force

# Proxy configuration
./BrowserStackLocal --key YOUR_ACCESS_KEY \
  --proxy-host proxy.example.com \
  --proxy-port 8080

Selenium Automation

Node.js

const { Builder } = require("selenium-webdriver");

const capabilities = {
  "bstack:options": {
    os: "Windows",
    osVersion: "11",
    browserVersion: "latest",
    projectName: "My Project",
    buildName: "Build 1.0",
    sessionName: "Homepage Test",
    local: "false",
    userName: process.env.BROWSERSTACK_USERNAME,
    accessKey: process.env.BROWSERSTACK_ACCESS_KEY,
  },
  browserName: "Chrome",
};

async function runTest() {
  const driver = new Builder()
    .usingServer("https://hub-cloud.browserstack.com/wd/hub")
    .withCapabilities(capabilities)
    .build();

  try {
    await driver.get("https://example.com");
    const title = await driver.getTitle();
    console.log("Title:", title);

    // Mark test as passed
    await driver.executeScript(
      'browserstack_executor: {"action": "setSessionStatus", "arguments": {"status":"passed","reason":"Title verified"}}'
    );
  } finally {
    await driver.quit();
  }
}

Python

from selenium import webdriver

options = webdriver.ChromeOptions()
options.set_capability("bstack:options", {
    "os": "Windows",
    "osVersion": "11",
    "browserVersion": "latest",
    "projectName": "My Project",
    "buildName": "Build 1.0",
    "userName": os.environ["BROWSERSTACK_USERNAME"],
    "accessKey": os.environ["BROWSERSTACK_ACCESS_KEY"],
})

driver = webdriver.Remote(
    command_executor="https://hub-cloud.browserstack.com/wd/hub",
    options=options,
)

driver.get("https://example.com")
print(driver.title)
driver.quit()

Cypress Integration

# Initialize BrowserStack Cypress config
npx browserstack-cypress init

# Run tests
npx browserstack-cypress run

# Run with specific config
npx browserstack-cypress run --config-file browserstack.json

{
  "auth": {
    "username": "YOUR_USERNAME",
    "access_key": "YOUR_ACCESS_KEY"
  },
  "browsers": [
    {
      "browser": "chrome",
      "os": "Windows 11",
      "versions": ["latest", "latest-1"]
    },
    {
      "browser": "firefox",
      "os": "OS X Sonoma",
      "versions": ["latest"]
    }
  ],
  "run_settings": {
    "cypress_config_file": "./cypress.config.js",
    "project_name": "My Project",
    "build_name": "Build 1.0",
    "parallels": 5
  }
}

Mobile Testing (Appium)

const capabilities = {
  "bstack:options": {
    deviceName: "iPhone 15",
    osVersion: "17",
    projectName: "Mobile Tests",
    buildName: "Build 1.0",
    userName: process.env.BROWSERSTACK_USERNAME,
    accessKey: process.env.BROWSERSTACK_ACCESS_KEY,
  },
  browserName: "Safari",
};

// For native app testing
const appCapabilities = {
  "bstack:options": {
    deviceName: "Google Pixel 8",
    osVersion: "14.0",
    app: "bs://APP_HASH_FROM_UPLOAD",
    projectName: "App Tests",
  },
};

# Upload app for testing
curl -u "USERNAME:ACCESS_KEY" \
  -X POST https://api-cloud.browserstack.com/app-automate/upload \
  -F "file=@/path/to/app.apk"

BrowserStack API

Endpoint	Description
GET /automate/builds.json	List builds
GET /automate/builds/{id}/sessions.json	List sessions in a build
GET /automate/sessions/{id}.json	Get session details
DELETE /automate/sessions/{id}.json	Delete a session
GET /automate/sessions/{id}/logs	Get session logs
PUT /automate/sessions/{id}.json	Update session status

# List recent builds
curl -u "USERNAME:ACCESS_KEY" \
  https://api.browserstack.com/automate/builds.json

# Get session details
curl -u "USERNAME:ACCESS_KEY" \
  https://api.browserstack.com/automate/sessions/SESSION_ID.json

Advanced Usage

Parallel Testing

// Run tests in parallel across multiple browsers
const browsers = [
  { browserName: "Chrome", "bstack:options": { os: "Windows", osVersion: "11" } },
  { browserName: "Firefox", "bstack:options": { os: "Windows", osVersion: "11" } },
  { browserName: "Safari", "bstack:options": { os: "OS X", osVersion: "Sonoma" } },
];

const tests = browsers.map(async (caps) => {
  caps["bstack:options"].userName = process.env.BROWSERSTACK_USERNAME;
  caps["bstack:options"].accessKey = process.env.BROWSERSTACK_ACCESS_KEY;

  const driver = new Builder()
    .usingServer("https://hub-cloud.browserstack.com/wd/hub")
    .withCapabilities(caps)
    .build();

  // ... run test
  await driver.quit();
});

await Promise.all(tests);

Network Logs and Debugging

// Enable network logs
const capabilities = {
  "bstack:options": {
    networkLogs: "true",
    consoleLogs: "verbose",
    debug: "true",
    video: "true",
  },
};

CI/CD Integration (GitHub Actions)

# .github/workflows/browserstack.yml
name: BrowserStack Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: browserstack/github-actions/setup-env@master
        with:
          username: ${{ secrets.BROWSERSTACK_USERNAME }}
          access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
      - uses: browserstack/github-actions/setup-local@master
      - run: npm test

Configuration

# Environment variables
export BROWSERSTACK_USERNAME="your_username"
export BROWSERSTACK_ACCESS_KEY="your_access_key"
export BROWSERSTACK_BUILD_NAME="CI Build #${BUILD_NUMBER}"

# .browserstack.yml
username: ${BROWSERSTACK_USERNAME}
access_key: ${BROWSERSTACK_ACCESS_KEY}
project_name: "My Project"
build_name: "Build 1.0"

Troubleshooting

Issue	Solution
Local tunnel not connecting	Check firewall; use --verbose 3 for debug output
Session timeout	Increase timeout in capabilities; default is 90 seconds
App upload fails	Check file size (< 200MB); verify API credentials
Tests queued too long	Check parallel limit on your plan; reduce concurrency
Video not recorded	Ensure video: true in capabilities
Selenium version mismatch	Specify seleniumVersion in bstack:options
Flaky tests	Use explicit waits; enable debug and networkLogs
Local testing 404s	Verify local server is running; check --force-local flag