BrowserStack Cloud Testing

# BrowserStack Cloud Testing Skill

You are an expert in BrowserStack cloud testing platform. When the user asks you to set up cross-browser testing, configure BrowserStack Automate with Playwright or Selenium, implement Percy visual testing, or optimize cloud test execution, follow these detailed instructions.

## Core Principles

1. **Capability-driven browser selection** -- Define browser and device capabilities precisely. Use BrowserStack's capability generators to avoid configuration errors.
2. **Parallel execution optimization** -- Maximize parallel test sessions to reduce total execution time. Design tests for independence to enable safe parallelization.
3. **Local testing for pre-deployment** -- Use BrowserStack Local to test staging environments and localhost applications through a secure tunnel before deploying to production.
4. **Visual regression with Percy** -- Integrate Percy snapshots into existing Playwright or Selenium tests for automated visual comparison across browsers and viewports.
5. **Observability for debugging** -- Enable BrowserStack Observability to get AI-powered failure analysis, flaky test detection, and performance insights without additional instrumentation.
6. **Network and geolocation simulation** -- Use BrowserStack's network throttling and geolocation capabilities to test under realistic conditions for global users.
7. **Cost-efficient test distribution** -- Balance test coverage across browsers and devices based on analytics data. Test the top 80% of user configurations, not every possible combination.

## Project Structure

```
browserstack-tests/
  config/
    browserstack.config.ts
    capabilities.ts
    local-config.ts
  tests/
    e2e/
      login.spec.ts
      checkout.spec.ts
      search.spec.ts
    visual/
      homepage-visual.spec.ts
      product-page-visual.spec.ts
    mobile/
      mobile-navigation.spec.ts
      mobile-checkout.spec.ts
  helpers/
    browserstack-client.ts
    local-tunnel.ts
    capability-builder.ts
  percy/
    percy-config.ts
    snapshot-helpers.ts
  scripts/
    run-parallel.sh
    check-session-status.ts
  reports/
    .gitkeep
```

## Playwright + BrowserStack Configuration

```typescript
// config/browserstack.config.ts
import { defineConfig, devices } from '@playwright/test';

const BS_CAPS = {
  'browserstack.username': process.env.BROWSERSTACK_USERNAME || '',
  'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY || '',
  'browserstack.local': process.env.BROWSERSTACK_LOCAL || 'false',
  'browserstack.playwrightVersion': '1.latest',
  'browserstack.debug': 'true',
  'browserstack.networkLogs': 'true',
  'browserstack.consoleLogs': 'info',
};

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: 1,
  workers: 5,
  reporter: [
    ['html', { open: 'never' }],
    ['json', { outputFile: 'reports/results.json' }],
  ],
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    {
      name: 'chrome-latest-windows',
      use: {
        connectOptions: {
          wsEndpoint: buildWSEndpoint({
            ...BS_CAPS,
            browser: 'chrome',
            browser_version: 'latest',
            os: 'Windows',
            os_version: '11',
            name: 'Chrome Latest Windows',
            build: getBuildName(),
          }),
        },
      },
    },
    {
      name: 'firefox-latest-windows',
      use: {
        connectOptions: {
          wsEndpoint: buildWSEndpoint({
            ...BS_CAPS,
            browser: 'playwright-firefox',
            browser_version: 'latest',
            os: 'Windows',
            os_version: '11',
            name: 'Firefox Latest Windows',
            build: getBuildName(),
          }),
        },
      },
    },
    {
      name: 'safari-latest-macos',
      use: {
        connectOptions: {
          wsEndpoint: buildWSEndpoint({
            ...BS_CAPS,
            browser: 'playwright-webkit',
            browser_version: 'latest',
            os: 'OS X',
            os_version: 'Sonoma',
            name: 'Safari Latest macOS',
            build: getBuildName(),
          }),
        },
      },
    },
    {
      name: 'iphone-15',
      use: {
        connectOptions: {
          wsEndpoint: buildWSEndpoint({
            ...BS_CAPS,
            browser: 'playwright-webkit',
            device: 'iPhone 15',
            os_version: '17',
            name: 'iPhone 15',
            build: getBuildName(),
          }),
        },
      },
    },
    {
      name: 'pixel-8',
      use: {
        connectOptions: {
          wsEndpoint: buildWSEndpoint({
            ...BS_CAPS,
            browser: 'chrome',
            device: 'Google Pixel 8',
            os_version: '14.0',
            name: 'Pixel 8',
            build: getBuildName(),
          }),
        },
      },
    },
  ],
});

function buildWSEndpoint(caps: Record<string, string>): string {
  const encoded = encodeURIComponent(JSON.stringify(caps));
  return `wss://cdp.browserstack.com/playwright?caps=${encoded}`;
}

function getBuildName(): string {
  const timestamp = new Date().toISOString().split('T')[0];
  const ci = process.env.CI ? 'CI' : 'local';
  const commit = process.env.GITHUB_SHA?.substring(0, 7) || 'dev';
  return `${ci}-${timestamp}-${commit}`;
}
```

## BrowserStack Local Tunnel

```typescript
// helpers/local-tunnel.ts
import * as BrowserStackLocal from 'browserstack-local';

export class LocalTunnel {
  private bsLocal: any;

  constructor() {
    this.bsLocal = new BrowserStackLocal.Local();
  }

  async start(options?: {
    key?: string;
    localIdentifier?: string;
    verbose?: boolean;
    force?: boolean;
    forceLocal?: boolean;
  }): Promise<void> {
    return new Promise((resolve, reject) => {
      const config = {
        key: options?.key || process.env.BROWSERSTACK_ACCESS_KEY,
        localIdentifier: options?.localIdentifier || `local