Testing Cross-Browser Compatibility

This skill validates application consistency across browsers and viewports, using intelligent testing strategies that account for known browser-specific quirks rather than naive screenshot comparison.

When to Use

• After CSS changes to verify cross-browser consistency
• Before release to validate the browser support matrix
• When users report "it works in Chrome but not Safari"
• To audit responsive design breakpoints
• When migrating CSS frameworks or removing polyfills

Workflow

Step 1 — Define the Test Matrix

Generate a matrix from the default or custom configuration:

from scripts.browser_setup import generate_browser_matrix

# Default: 3 browsers × 3 viewports = 9 combinations
matrix = generate_browser_matrix()

# Custom matrix
matrix = generate_browser_matrix(
    browsers=["chromium", "webkit"],
    viewports=["mobile-portrait", "desktop"],
)

Or provide a JSON configuration:

{
  "browsers": ["chromium", "firefox", "webkit"],
  "viewports": ["mobile-portrait", "tablet-portrait", "desktop"],
  "pages": ["/", "/login", "/dashboard", "/checkout"],
  "reference": "chromium-desktop"
}

Step 2 — Capture Across Matrix

Use the matrix runner to capture all combinations:

python skills/qa-testing-cross-browser-compatibility/scripts/matrix_runner.py \
  --url https://staging.example.com \
  --matrix matrix.json \
  --output browser-results/captures/

This captures screenshots of each page in each browser × viewport combination.

Step 3 — Cross-Comparison

Compare all combinations against the reference (default: Chromium Desktop):

python skills/qa-testing-cross-browser-compatibility/scripts/cross_compare.py \
  --captures browser-results/captures/ \
  --reference chromium-desktop \
  --output browser-results/

Step 4 — Functional Validation

Beyond visual comparison, test browser-specific functionality:

python skills/qa-testing-cross-browser-compatibility/scripts/functional_check.py \
  --url https://staging.example.com \
  --matrix matrix.json \
  --output browser-results/functional/

Browser-Specific Quirks to Test

WebKit (Safari / iOS)

Safari has the most rendering differences from Chromium. Always check:

• 100vh issue: On mobile Safari, 100vh includes the toolbar area, pushing content below the fold. Use 100dvh or JavaScript-based height calculation.
• position: sticky: Can break inside overflow containers or with -webkit-overflow-scrolling: touch
• Date inputs: Safari renders date pickers differently; <input type="date"> may not support min/max attributes properly
• Backdrop-filter: Requires -webkit-backdrop-filter prefix
• Flexbox gaps: Older Safari versions don't support gap in flexbox (only grid)
• Scroll behavior: scroll-behavior: smooth support is inconsistent
• Font rendering: Safari uses different font smoothing, affecting text width calculations
• Form elements: Select dropdowns, checkboxes, and radio buttons render with platform-native styling that can't be fully overridden

Firefox

Firefox follows standards strictly, which sometimes differs from Chromium's behavior:

• Scrollbar styling: Uses scrollbar-width and scrollbar-color instead of ::-webkit-scrollbar
• Form element styling: More resistant to custom form styling
• CSS Grid subgrid: Firefox had earlier subgrid support; check for Chrome compatibility
• Text overflow: Slightly different text wrapping calculations
• accent-color: May render differently on form elements
• Print styling: Firefox has stricter print stylesheet handling

Chromium (Chrome / Edge)

Usually the most forgiving, but watch for:

• Over-reliance on -webkit- prefixes that won't work elsewhere
• Experimental CSS features enabled by default in Chrome but not in other browsers
• Extension interference — test in incognito mode
• Memory usage — heavy DOM operations may perform differently

Viewport-Specific Checks

Mobile (< 768px)

• Touch targets are at least 44×44px
• No horizontal scroll (overflow-x)
• Navigation collapses to hamburger menu
• Font sizes are readable without zooming (≥16px)
• Forms don't zoom in on focus (set font-size ≥ 16px on inputs)
• Tap-to-call on phone numbers works

Tablet (768px – 1024px)

• Layout adapts between mobile and desktop breakpoints
• Side panels collapse or become toggleable
• Tables scroll horizontally or restructure
• Images resize proportionally

Desktop (> 1024px)

• Content doesn't stretch beyond max-width
• Hover states are visible and responsive
• Keyboard navigation works for all interactive elements
• Multi-column layouts render correctly

Issue Classification

When a difference is found, classify it:

Browser-specific bug: Appears in one browser, all viewports → Likely a CSS prefix issue or unsupported property

Viewport-specific bug: Appears in one viewport, all browsers → Likely a responsive design / media query issue

Compound bug: One specific browser × viewport combination → May be an interaction between browser rendering and responsive rules

Universal inconsistency: Different from Figma in all combinations → Implementation doesn't match design (not a browser issue)

Output

browser-results/
├── matrix.json                    ← executed test matrix
├── captures/
│   ├── chromium-desktop/
│   │   ├── homepage.png
│   │   └── checkout.png
│   ├── firefox-desktop/
│   ├── webkit-mobile-portrait/
│   └── ...
├── comparisons/
│   ├── homepage-cross-browser.json
│   └── checkout-cross-browser.json
├── functional/
│   ├── chromium-desktop.json
│   └── webkit-mobile-portrait.json
├── bugs/
│   └── bug-001-webkit-sticky-header.json
└── browser-summary.md

Each bug includes affected_browsers and affected_viewports arrays so developers know exactly which environments to target.