Cross Browser Testing

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
// => Import Playwright configuration API
// => devices provides standardized browser configs

export default defineConfig({
  // => Defines root-level test configuration
  projects: [
    {
      name: "chromium",
      // => Project name for test reporting
      use: { ...devices["Desktop Chrome"] },
      // => Spread Desktop Chrome device config
      // => Includes viewport, user agent, device scale factor
    },
    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"] },
      // => Firefox with Gecko rendering engine
      // => Different CSS and JavaScript behavior
    },
    {
      name: "webkit",
      use: { ...devices["Desktop Safari"] },
      // => WebKit engine (Safari implementation)
      // => Critical for iOS compatibility validation
    },
  ],
  // => Runs ALL tests in ALL projects by default
});

// tests/cross-browser/navigation.spec.ts
import { test, expect } from "@playwright/test";
// => Standard Playwright test API
// => No project-specific imports needed

test("navigation menu renders consistently", async ({ page }) => {
  // => Test executes 3 times (once per project)
  // => Each execution receives different browser context

  await page.goto("https://example.com");
  // => Navigates in current project's browser
  // => Chromium, Firefox, or WebKit

  const menuItems = await page.locator("nav li").count();
  // => Counts navigation items
  // => CSS rendering may differ per browser

  expect(menuItems).toBe(5);
  // => Validates expected structure
  // => Fails if browser-specific CSS breaks layout

  await page.click("nav li:first-child a");
  // => Clicks first navigation link
  // => Click behavior consistent across engines

  await expect(page).toHaveURL(/\/about/);
  // => Validates navigation occurred
  // => URL handling standardized across browsers
});

# Run all projects (all browsers)
npx playwright test
# => Executes tests in chromium, firefox, webkit sequentially
# => Total test count: <test_count> × 3 browsers

# Run specific project
npx playwright test --project=firefox
# => Executes tests ONLY in Firefox
# => Useful for debugging browser-specific failures

# Install BrowserStack integration
npm install --save-dev @browserstack/playwright
# => Adds BrowserStack Playwright adapter
# => Provides cloud browser connection capabilities

// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";
// => Standard Playwright configuration API

export default defineConfig({
  use: {
    // => Global configuration for ALL tests
    connectOptions: {
      wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(
        JSON.stringify({
          "browserstack.username": process.env.BROWSERSTACK_USERNAME,
          // => Authentication username from environment
          // => NEVER hardcode credentials
          "browserstack.accessKey": process.env.BROWSERSTACK_ACCESS_KEY,
          // => Authentication key from environment
          // => Secured via CI/CD secrets
          project: "Cross-Browser Production Tests",
          // => BrowserStack project grouping
          // => Organizes test runs in dashboard
          build: `Build ${process.env.CI_BUILD_ID || "local"}`,
          // => Build identifier for tracking
          // => Groups related test runs
          name: "Playwright Cross-Browser Suite",
          // => Test session name
        }),
      )}`,
      // => WebSocket endpoint for Playwright CDP connection
      // => Connects local Playwright to cloud browsers
    },
    screenshot: "only-on-failure",
    // => Captures screenshots for failed tests
    // => Uploaded to BrowserStack for debugging
    video: "retain-on-failure",
    // => Records video for failed tests
    // => Critical for debugging cross-browser issues
    trace: "retain-on-failure",
    // => Generates Playwright trace files
    // => Enables detailed timeline debugging
  },

  projects: [
    {
      name: "chrome-windows-latest",
      use: {
        ...devices["Desktop Chrome"],
        // => Base Chromium configuration
        connectOptions: {
          wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(
            JSON.stringify({
              browser: "chrome",
              browser_version: "latest",
              // => Latest stable Chrome version
              // => BrowserStack auto-updates
              os: "Windows",
              os_version: "11",
              // => Windows 11 environment
              // => Real OS, not virtualized
              "browserstack.username": process.env.BROWSERSTACK_USERNAME,
              "browserstack.accessKey": process.env.BROWSERSTACK_ACCESS_KEY,
            }),
          )}`,
        },
      },
    },
    {
      name: "firefox-macos-latest",
      use: {
        ...devices["Desktop Firefox"],
        connectOptions: {
          wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(
            JSON.stringify({
              browser: "firefox",
              browser_version: "latest",
              // => Latest Firefox release
              os: "OS X",
              os_version: "Ventura",
              // => macOS Ventura environment
              // => Tests native Safari rendering
              "browserstack.username": process.env.BROWSERSTACK_USERNAME,
              "browserstack.accessKey": process.env.BROWSERSTACK_ACCESS_KEY,
            }),
          )}`,
        },
      },
    },
    {
      name: "safari-macos-latest",
      use: {
        ...devices["Desktop Safari"],
        connectOptions: {
          wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(
            JSON.stringify({
              browser: "safari",
              browser_version: "latest",
              // => Latest Safari version
              // => Only available on macOS
              os: "OS X",
              os_version: "Ventura",
              "browserstack.username": process.env.BROWSERSTACK_USERNAME,
              "browserstack.accessKey": process.env.BROWSERSTACK_ACCESS_KEY,
            }),
          )}`,
        },
      },
    },
    {
      name: "edge-windows-latest",
      use: {
        ...devices["Desktop Edge"],
        // => Edge uses Chromium engine
        // => But includes Edge-specific features
        connectOptions: {
          wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(
            JSON.stringify({
              browser: "edge",
              browser_version: "latest",
              os: "Windows",
              os_version: "11",
              "browserstack.username": process.env.BROWSERSTACK_USERNAME,
              "browserstack.accessKey": process.env.BROWSERSTACK_ACCESS_KEY,
            }),
          )}`,
        },
      },
    },
  ],

  workers: 5,
  // => Parallel execution across 5 cloud browsers
  // => BrowserStack charges by concurrent session
  // => Adjust based on plan limits

  retries: 1,
  // => Retry failed tests once
  // => Handles transient network issues

  timeout: 60000,
  // => 60-second timeout per test
  // => Cloud tests slower due to network latency
});

// tests/cross-browser/form-validation.spec.ts
import { test, expect } from "@playwright/test";
// => Standard Playwright test API
// => Works with both local and cloud browsers

test.describe("Form validation across browsers", () => {
  test.beforeEach(async ({ page }) => {
    // => Runs before each test
    // => Sets up consistent starting state

    await page.goto("https://example.com/form");
    // => Navigates to form page
    // => Cloud browsers load from real network
  });

  test("email validation displays consistently", async ({ page, browserName }) => {
    // => browserName injected by Playwright
    // => Values: 'chromium', 'firefox', 'webkit'

    const emailInput = page.locator('input[type="email"]');
    // => Email input selector
    // => Standard across browsers

    await emailInput.fill("invalid-email");
    // => Enters invalid email
    // => Tests HTML5 validation behavior

    await page.click('button[type="submit"]');
    // => Submits form
    // => Triggers validation

    if (browserName === "webkit") {
      // => Safari/WebKit-specific behavior
      // => Uses different validation UI

      const validationMessage = await emailInput.evaluate((el: HTMLInputElement) => el.validationMessage);
      // => Accesses native validation message
      // => WebKit shows custom dialog

      expect(validationMessage).toContain("email");
      // => Validates message contains "email"
      // => Exact text varies by browser
    } else {
      // => Chrome/Firefox standard behavior
      const validationBubble = page.locator(".validation-error");
      // => Custom validation UI selector
      // => Consistent in Chromium/Firefox

      await expect(validationBubble).toBeVisible();
      // => Validates error displays
      // => May not exist in WebKit
    }
  });

  test("date picker handles browser differences", async ({ page, browserName }) => {
    const dateInput = page.locator('input[type="date"]');
    // => Date input selector
    // => Native implementation varies

    const isNativeSupported = await dateInput.evaluate((el: HTMLInputElement) => {
      // => Executes in browser context
      // => Checks native date picker support

      const testInput = document.createElement("input");
      testInput.setAttribute("type", "date");
      return testInput.type === "date";
      // => Returns true if browser supports native date picker
      // => Safari supports, older browsers may not
    });

    if (isNativeSupported) {
      // => Use native date picker
      // => Chrome, Firefox, Safari modern versions

      await dateInput.fill("2024-12-31");
      // => Standard date format (YYYY-MM-DD)
      // => Works across native implementations

      const value = await dateInput.inputValue();
      // => Retrieves input value
      // => Format consistent across browsers

      expect(value).toBe("2024-12-31");
      // => Validates date stored correctly
    } else {
      // => Fallback to custom date picker
      // => Older browsers or non-native implementations

      await page.click('input[type="date"]');
      // => Opens custom date picker

      await page.click('[data-testid="calendar-day-31"]');
      // => Clicks specific day
      // => Custom calendar component

      const displayValue = await page.locator(".date-display").textContent();
      expect(displayValue).toContain("Dec 31");
      // => Validates display format
    }
  });

  test("file upload works across operating systems", async ({ page }) => {
    const fileInput = page.locator('input[type="file"]');
    // => File input selector
    // => Works across all browsers

    await fileInput.setInputFiles({
      name: "test-document.pdf",
      mimeType: "application/pdf",
      buffer: Buffer.from("%PDF-1.4 mock content"),
      // => Creates mock PDF file
      // => Works in cloud browsers without real files
    });
    // => Simulates file selection
    // => No OS dialog interaction needed

    const uploadedFileName = await page.locator(".uploaded-file-name").textContent();
    // => Retrieves displayed filename

    expect(uploadedFileName).toContain("test-document.pdf");
    // => Validates file upload succeeded

    await page.click('button[type="submit"]');
    // => Submits form with file

    await expect(page.locator(".upload-success")).toBeVisible({ timeout: 10000 });
    // => Validates upload completed
    // => Increased timeout for cloud network latency
  });
});

# .env.browserstack
BROWSERSTACK_USERNAME=your_username_here
# => BrowserStack account username
# => Load from CI/CD secrets in production

BROWSERSTACK_ACCESS_KEY=your_access_key_here
# => BrowserStack API access key
# => NEVER commit to version control

CI_BUILD_ID=local
# => Build identifier (overridden in CI)
# => Groups test runs

// package.json scripts
{
  "scripts": {
    "test:cross-browser": "playwright test",
    // => Runs all projects (all browsers)
    // => Uses BrowserStack cloud infrastructure

    "test:cross-browser:chrome": "playwright test --project=chrome-windows-latest",
    // => Tests Chrome on Windows 11 only

    "test:cross-browser:safari": "playwright test --project=safari-macos-latest",
    // => Tests Safari on macOS only

    "test:cross-browser:parallel": "playwright test --workers=10",
    // => Increases parallelization to 10 workers
    // => Requires BrowserStack plan supporting 10 concurrent sessions
  }
}

// playwright.config.ts - Strategic browser matrix
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  projects: [
    // Desktop browsers - 70% of traffic
    {
      name: "chrome-desktop",
      use: {
        ...devices["Desktop Chrome"],
        viewport: { width: 1920, height: 1080 },
        // => Full HD resolution
        // => Most common desktop viewport
      },
    },
    {
      name: "firefox-desktop",
      use: {
        ...devices["Desktop Firefox"],
        viewport: { width: 1920, height: 1080 },
        // => Gecko engine validation
        // => Critical for CSS compatibility
      },
    },
    {
      name: "safari-desktop",
      use: {
        ...devices["Desktop Safari"],
        viewport: { width: 1440, height: 900 },
        // => MacBook standard resolution
        // => WebKit engine (iOS preview)
      },
    },

    // Mobile browsers - 30% of traffic
    {
      name: "mobile-safari",
      use: {
        ...devices["iPhone 14 Pro"],
        // => iOS Safari (WebKit)
        // => Cannot be tested on Windows/Linux locally
      },
    },
    {
      name: "mobile-chrome",
      use: {
        ...devices["Pixel 7"],
        // => Android Chrome (Blink)
        // => Mobile viewport and touch events
      },
    },
  ],

  // Test sharding for CI/CD
  shard: process.env.CI
    ? { current: Number(process.env.SHARD_INDEX), total: Number(process.env.SHARD_TOTAL) }
    : undefined,
  // => Splits tests across CI machines
  // => Each machine runs subset of browsers
  // => Example: SHARD_INDEX=1 SHARD_TOTAL=3 runs first third
});

// tests/utils/browser-selectors.ts
import { Page } from "@playwright/test";

export class BrowserAwareSelectors {
  // => Encapsulates browser-specific selector logic
  // => Centralizes workarounds

  static async selectDate(page: Page, date: string): Promise<void> {
    // => Handles date picker across browsers
    // => Abstracts browser differences

    const browserName = page.context().browser()?.browserType().name();
    // => Retrieves current browser type
    // => 'chromium', 'firefox', or 'webkit'

    const dateInput = page.locator('input[type="date"]');

    if (browserName === "webkit") {
      // => Safari uses native date picker
      // => Different interaction model

      await dateInput.focus();
      // => Focuses input to show native picker

      await page.keyboard.type(date.replace(/-/g, ""));
      // => Types date without separators
      // => Safari expects MMDDYYYY format
    } else {
      // => Chrome/Firefox support standard fill
      await dateInput.fill(date);
      // => YYYY-MM-DD format
      // => Standard HTML5 behavior
    }
  }

  static async handleDialog(page: Page, action: "accept" | "dismiss"): Promise<void> {
    // => Handles alert/confirm dialogs
    // => Browser implementations differ

    const browserName = page.context().browser()?.browserType().name();

    page.on("dialog", async (dialog) => {
      // => Listens for dialog events
      // => Fires on alert(), confirm(), prompt()

      if (browserName === "webkit" && dialog.type() === "beforeunload") {
        // => Safari handles beforeunload differently
        // => Must explicitly dismiss

        await dialog.dismiss();
        // => Prevents navigation hang
      } else if (action === "accept") {
        await dialog.accept();
        // => Clicks OK/Yes
      } else {
        await dialog.dismiss();
        // => Clicks Cancel/No
      }
    });
  }

  static async waitForAnimation(page: Page, selector: string): Promise<void> {
    // => Waits for CSS animations to complete
    // => Timing differs across browsers

    const browserName = page.context().browser()?.browserType().name();
    const element = page.locator(selector);

    await element.waitFor({ state: "visible" });
    // => Ensures element rendered

    if (browserName === "firefox") {
      // => Firefox processes animations differently
      // => Needs extra wait for smooth transitions

      await page.waitForTimeout(100);
      // => Allows Firefox to complete GPU compositing
      // => Prevents flaky screenshot diffs
    }

    await element.evaluate((el: HTMLElement) => {
      // => Executes in browser context
      // => Checks animation state

      return Promise.all(el.getAnimations().map((animation) => animation.finished));
      // => Waits for ALL animations to finish
      // => getAnimations() returns Web Animations API objects
    });
  }
}

// tests/cloud/browserstack-runner.ts
import { test as base, expect } from "@playwright/test";
import axios from "axios";
// => HTTP client for BrowserStack API
// => Reports test status to dashboard

interface BrowserStackFixtures {
  sessionId: string;
  // => BrowserStack session identifier
  // => Used for API calls
}

export const test = base.extend<BrowserStackFixtures>({
  sessionId: async ({ page }, use) => {
    // => Custom fixture for session management
    // => Runs before each test

    const cdpSession = await page.context().newCDPSession(page);
    // => Creates Chrome DevTools Protocol session
    // => Enables low-level browser control

    const sessionInfo = await cdpSession.send("Browser.getVersion");
    // => Retrieves browser metadata
    // => Includes session ID

    const sessionId = sessionInfo.userAgent.match(/sessionId=([^;]+)/)?.[1] || "unknown";
    // => Extracts BrowserStack session ID from user agent
    // => Used for status updates

    await use(sessionId);
    // => Provides sessionId to test
    // => Cleanup runs after test completes
  },
});

test.afterEach(async ({ page, sessionId }, testInfo) => {
  // => Runs after EACH test
  // => Reports status to BrowserStack

  const status = testInfo.status === "passed" ? "passed" : "failed";
  // => Maps Playwright status to BrowserStack status

  const reason = testInfo.error?.message || "";
  // => Captures failure reason
  // => Displayed in BrowserStack dashboard

  try {
    await axios.put(
      `https://api.browserstack.com/automate/sessions/${sessionId}.json`,
      // => BrowserStack session update API
      // => Updates test status
      {
        status,
        reason,
        name: testInfo.title,
        // => Test name from describe/test blocks
      },
      {
        auth: {
          username: process.env.BROWSERSTACK_USERNAME!,
          password: process.env.BROWSERSTACK_ACCESS_KEY!,
        },
        // => HTTP Basic Auth
        // => Authenticates API request
        timeout: 5000,
        // => 5-second timeout for API call
        // => Prevents hanging on network issues
      },
    );
    // => Updates session with test result
    // => Enables filtering in BrowserStack dashboard
  } catch (error) {
    // => Catches API errors
    // => Does NOT fail test (best effort)

    console.warn(`Failed to update BrowserStack session ${sessionId}:`, error);
    // => Logs warning
    // => Test result unaffected
  }
});

test.describe("Cloud testing with error handling", () => {
  test("handles network timeouts gracefully", async ({ page }) => {
    // => Tests network resilience
    // => Critical for cloud environments

    test.setTimeout(90000);
    // => Increases timeout to 90 seconds
    // => Accounts for cloud latency

    let retries = 0;
    const maxRetries = 3;
    // => Retry configuration
    // => Handles transient failures

    while (retries < maxRetries) {
      try {
        await page.goto("https://example.com", {
          timeout: 30000,
          // => 30-second navigation timeout
          // => Prevents infinite hangs
          waitUntil: "networkidle",
          // => Waits for network to be idle
          // => Ensures page fully loaded
        });

        break;
        // => Success - exit retry loop
      } catch (error) {
        retries++;
        // => Increment retry counter

        if (retries >= maxRetries) {
          throw error;
          // => Max retries exceeded - fail test
        }

        console.log(`Navigation attempt ${retries} failed, retrying...`);
        // => Logs retry attempt

        await page.waitForTimeout(2000 * retries);
        // => Exponential backoff
        // => 2s, 4s, 6s delays
      }
    }

    await expect(page).toHaveURL("https://example.com/");
    // => Validates successful navigation
  });

  test("validates quota limits", async ({ page, sessionId }) => {
    // => Tests BrowserStack quota handling
    // => Prevents silent failures

    const response = await axios.get("https://api.browserstack.com/automate/plan.json", {
      auth: {
        username: process.env.BROWSERSTACK_USERNAME!,
        password: process.env.BROWSERSTACK_ACCESS_KEY!,
      },
    });
    // => Retrieves account plan details
    // => Checks parallel session limits

    const { parallel_sessions_running, parallel_sessions_max_allowed } = response.data;
    // => Extracts current and max sessions

    if (parallel_sessions_running >= parallel_sessions_max_allowed) {
      // => Quota limit reached
      // => Tests will queue or fail

      test.skip();
      // => Skips test gracefully
      // => Prevents quota overage charges

      console.warn("BrowserStack parallel session limit reached");
    }
  });
});

// ❌ WRONG - Hardcoded credentials
connectOptions: {
  wsEndpoint: 'wss://cdp.browserstack.com/playwright?caps={"browserstack.username":"user","browserstack.accessKey":"key123"}';
}

// ✅ RIGHT - Environment variables
connectOptions: {
  wsEndpoint: `wss://cdp.browserstack.com/playwright?caps=${encodeURIComponent(
    JSON.stringify({
      "browserstack.username": process.env.BROWSERSTACK_USERNAME,
      "browserstack.accessKey": process.env.BROWSERSTACK_ACCESS_KEY,
    }),
  )}`;
}

// Enable strict SSL validation
connectOptions: {
  wsEndpoint: 'wss://cdp.browserstack.com/playwright...',
  headers: {
    'User-Agent': 'Playwright Cross-Browser Tests',
    // => Identifies test traffic
  },
}

const isClipboardSupported = await page.evaluate(() => {
  return !!navigator.clipboard && typeof navigator.clipboard.writeText === "function";
});

if (isClipboardSupported) {
  // Use clipboard API
} else {
  // Fallback: show copy button
}

// Use viewport-aware selectors
const menuButton = page.locator("[data-mobile-menu], nav > ul");
// => Matches mobile menu button OR desktop nav
// => Adapts to viewport size

workers: process.env.BROWSERSTACK_PLAN === 'team' ? 5 : 10,
// => Matches BrowserStack plan limits
// => Prevents quota overages

test.setTimeout(process.env.CI ? 90000 : 30000);
// => 90s timeout in CI (cloud browsers)
// => 30s timeout locally

test("mobile touch interactions", async ({ page }) => {
  await page.tap('[data-testid="menu-toggle"]');
  // => Uses tap instead of click
  // => Simulates mobile touch
});