Cross-Browser Testing

CSS Compatibility Testing: Catch Browser-Specific Style Bugs Automatically

HelpMeTest

HelpMeTest

— 7 min read
CSS Compatibility Testing: Catch Browser-Specific Style Bugs Automatically

CSS compatibility bugs are uniquely frustrating. They're often invisible to the developer who wrote the code (because they tested in one browser), they appear at the worst possible time (production, customer demo, launch day), and they range from trivial (slightly wrong font weight) to catastrophic (entire layout broken, button not clickable). The good news is that most CSS compatibility issues are preventable through automation — linting, prefixing, and visual regression testing catch the majority of them before any user sees them.

This guide covers the full stack: using the Can I Use API to understand what to test, PostCSS autoprefixer to handle vendor prefixes at build time, Stylelint's browser compatibility plugin to catch unsupported properties in CI, and visual regression testing to catch the style bugs that slip through static analysis.

Understanding the CSS Compatibility Problem

CSS compatibility issues fall into three categories:

Unsupported properties: Using aspect-ratio in a browser that doesn't support it (Safari before 15), or gap in flex containers on Firefox before 63. The element either falls back silently or breaks completely.

Vendor-prefixed properties: -webkit-transform vs transform, -moz-border-radius vs border-radius. Modern browsers have converged, but you're still shipping to users on older iOS Safari versions that need prefixes for certain properties.

Implementation differences: Both browsers "support" the property but render it differently. position: sticky behavior at table boundaries, z-index stacking context differences, flexbox gap behavior in wrapped containers — these all "work" but produce different visual results.

Static analysis (linting and build-time checks) handles the first two categories well. The third category requires visual regression testing.

The Can I Use API

Can I Use is the authoritative database of browser support for CSS properties, HTML features, and JavaScript APIs. The underlying data is available as a JSON package:

npm install caniuse-db --save-dev
# or use the lite version
npm install caniuse-lite --save-dev

You can query it programmatically to build custom compatibility checks:

const caniuse = require('caniuse-api');

// Check if a feature is supported across your target browsers
function checkFeatureSupport(feature, browsers) {
  const support = caniuse.getSupport(feature);
  const unsupported = [];
  
  browsers.forEach(browser => {
    const [name, version] = browser.split(' ');
    const browserSupport = support[name];
    
    if (!browserSupport || !browserSupport[version]) {
      unsupported.push(browser);
    }
  });
  
  return {
    feature,
    unsupported,
    supported: unsupported.length === 0
  };
}

// Define your browser targets
const targetBrowsers = [
  'chrome 110', 'chrome 120',
  'firefox 115', 'firefox 121',
  'safari 15', 'safari 16', 'safari 17',
  'edge 120'
];

// Features you're using in your codebase
const features = [
  'css-grid',
  'flexbox',
  'css-aspect-ratio',
  'css-container-queries',
  'has',  // :has() selector
  'css-nesting',
];

features.forEach(feature => {
  const result = checkFeatureSupport(feature, targetBrowsers);
  if (!result.supported) {
    console.warn(`⚠️  ${feature} not supported in: ${result.unsupported.join(', ')}`);
  }
});

This kind of script can run in CI as a pre-check before your test suite, flagging new CSS features in your codebase that fall outside your browser support matrix.

The caniuse-api package also powers Browserslist, which PostCSS autoprefixer and many other tools use internally. Your .browserslistrc file is the single source of truth for your browser targets:

# .browserslistrc
last 2 Chrome versions
last 2 Firefox versions
last 2 Edge versions
Safari >= 15
iOS >= 15
not dead
> 0.5%

PostCSS Autoprefixer: Vendor Prefixes at Build Time

Manually adding -webkit-, -moz-, and -ms- prefixes is error-prone and creates maintenance debt. PostCSS autoprefixer reads your Browserslist targets and adds the exact prefixes needed — no more, no less.

Setup

npm install --save-dev postcss autoprefixer
// postcss.config.js
module.exports = {
  plugins: [
    require('autoprefixer')
  ]
};

Autoprefixer reads .browserslistrc automatically. With the targets above, it will:

  • Add -webkit- prefixes for backdrop-filter (still needed for Safari)
  • Add -webkit- for appearance: none (form element styling)
  • Add -webkit-text-size-adjust for iOS
  • Skip prefixes that are now universally supported (like transform, transition)

Verifying autoprefixer is working:

# Process a CSS file and inspect output
npx postcss input.css --use autoprefixer -o output.css

# Use autoprefixer's built-in info command
npx autoprefixer --info

The --info output shows exactly which browsers your Browserslist targets resolve to and which prefixes autoprefixer will add.

Integrating with Vite, webpack, and other bundlers

Vite uses PostCSS config automatically:

// vite.config.js
export default {
  css: {
    postcss: './postcss.config.js'
  }
};

Create React App includes PostCSS and autoprefixer by default; you only need .browserslistrc.

webpack with css-loader:

{
  loader: 'postcss-loader',
  options: {
    postcssOptions: {
      plugins: [['autoprefixer', {}]]
    }
  }
}

CSS Grid Autoprefixer Caveat

Autoprefixer can transform modern CSS Grid into the older -ms-grid syntax for older IE/Edge support — but this transformation is not always reliable for complex grid layouts. If you're targeting older Edge, test grid layouts specifically. The autoprefixer documentation has a grid: "autoplace" option that enables the IE grid transformation with known limitations.

Stylelint Browser Compatibility Plugin

Autoprefixer fixes missing prefixes. Stylelint's browser compatibility plugin catches the deeper issue: using CSS properties that aren't supported at all in your target browsers.

npm install --save-dev stylelint stylelint-no-unsupported-browser-features
// .stylelintrc.js
module.exports = {
  plugins: ['stylelint-no-unsupported-browser-features'],
  rules: {
    'plugin/no-unsupported-browser-features': [
      true,
      {
        severity: 'error',
        ignore: [
          // Features you've deliberately accepted limited support for
          'css-scrollbar',  // Custom scrollbar styling, only for Chrome
          'css-overscroll-behavior',  // Progressive enhancement
        ],
        ignorePartialSupport: true,  // Don't error on "partial" support flags
      }
    ]
  }
};

Running Stylelint in CI:

npx stylelint "src/**/*.css" "src/**/*.scss"

Example output when a compatibility issue is found:

src/components/Dashboard/dashboard.css
  42:3  error  CSS property "container-type" is not supported in: Chrome 110  plugin/no-unsupported-browser-features

1 problem (1 error, 0 warnings)

This tells you exactly which line, which property, and which browser target is the problem — actionable and specific.

Handling False Positives

The Stylelint browser compatibility plugin can be noisy, especially for newer CSS features that are "partially supported" in some browsers. The ignorePartialSupport: true option reduces noise for features that mostly work but have edge case limitations. For intentional progressive enhancements (features that provide better experience where supported but don't break where they're not), add them to the ignore list with a comment explaining why.

// .stylelintrc.js
rules: {
  'plugin/no-unsupported-browser-features': [
    true,
    {
      ignore: [
        'css-scrollbar',          // Chrome-only scrollbar styling, progressive enhancement
        'css-backdrop-filter',    // Supported with -webkit- prefix via autoprefixer
        'css-scroll-snap',        // Supported in all targets, false positive in plugin data
      ]
    }
  ]
}

Visual Regression Testing for CSS Bugs

Static analysis catches unsupported properties and missing prefixes. It does not catch:

  • Subtle layout differences between browser rendering engines
  • Font metrics differences causing text truncation
  • Flexbox gap rendering in wrapped containers
  • position: sticky at different scroll positions
  • Animation timing and easing visual differences

Visual regression testing captures screenshots and compares them against baselines. When the diff exceeds a threshold, the test fails.

Playwright Screenshot Comparison

Playwright's built-in screenshot comparison is the simplest starting point:

import { test, expect } from '@playwright/test';

test('dashboard layout matches snapshot', async ({ page }, testInfo) => {
  await page.goto('/dashboard');
  await page.waitForLoadState('networkidle');
  
  // Hide dynamic content that changes between runs
  await page.evaluate(() => {
    document.querySelectorAll('[data-testid="timestamp"]').forEach(el => {
      (el as HTMLElement).style.visibility = 'hidden';
    });
  });
  
  await expect(page).toHaveScreenshot('dashboard.png', {
    maxDiffPixels: 50,        // Allow up to 50 pixels difference
    maxDiffPixelRatio: 0.01,  // Or up to 1% of pixels different
    threshold: 0.2,            // Per-pixel color threshold
    animations: 'disabled',    // Don't capture animations mid-state
  });
});

test('mobile navigation layout', async ({ page }) => {
  await page.setViewportSize({ width: 375, height: 812 });
  await page.goto('/');
  
  // Open the mobile menu
  await page.click('[data-testid="hamburger-menu"]');
  await expect(page.locator('[data-testid="mobile-nav"]')).toBeVisible();
  
  await expect(page.locator('[data-testid="mobile-nav"]')).toHaveScreenshot('mobile-nav.png');
});

Run with --update-snapshots to set or update baselines:

npx playwright test --update-snapshots

Playwright stores snapshots at tests/__snapshots__/test-name-chromium.png, tests/__snapshots__/test-name-firefox.png, tests/__snapshots__/test-name-webkit.png — separate baselines per browser. This is correct: rendering differences between browsers are expected and intentional; you're testing for regressions within a browser, not consistency across browsers.

Component-Level Visual Regression with Storybook

For component libraries, visual regression at the component level is more maintainable than full-page screenshots:

// stories/Button.stories.ts
export default {
  title: 'Components/Button',
  component: Button,
};

export const Primary = {
  args: { variant: 'primary', children: 'Click me' }
};

export const Disabled = {
  args: { variant: 'primary', children: 'Click me', disabled: true }
};
// tests/visual/button.visual.spec.ts
import { test, expect } from '@playwright/test';

const variants = ['primary', 'secondary', 'ghost', 'destructive'];
const states = ['default', 'hover', 'focus', 'disabled'];

for (const variant of variants) {
  for (const state of states) {
    test(`Button ${variant} ${state}`, async ({ page }) => {
      await page.goto(`/storybook/iframe.html?id=components-button--${variant}`);
      
      if (state === 'hover') {
        await page.hover('button');
      } else if (state === 'focus') {
        await page.focus('button');
      }
      
      await expect(page.locator('button')).toHaveScreenshot(`button-${variant}-${state}.png`);
    });
  }
}

This gives you 16 visual regression tests that catch CSS regressions in any button state across all browsers — automatically.

CI Workflow for Visual Regression

name: Visual Regression Tests

on:
  pull_request:
    paths:
      - 'src/**/*.css'
      - 'src/**/*.scss'
      - 'src/**/*.tsx'

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Playwright
        run: npx playwright install --with-deps chromium firefox webkit
      
      - name: Build Storybook
        run: npm run build-storybook
      
      - name: Serve Storybook
        run: npx serve storybook-static -p 6006 &
      
      - name: Wait for Storybook
        run: npx wait-on http://localhost:6006
      
      - name: Run visual regression tests
        run: npx playwright test tests/visual/
        env:
          BASE_URL: http://localhost:6006
      
      - name: Upload diff screenshots on failure
        uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: visual-regression-diffs
          path: test-results/

When visual regression tests fail, the uploaded artifacts contain three images per failure: the expected baseline, the actual screenshot, and a diff image highlighting exactly what changed.

Putting It All Together: The CSS Compatibility Pipeline

A complete CSS compatibility pipeline runs in this order:

  1. Browserslist validation — confirm your browser targets are what you intend
  2. PostCSS autoprefixer — add vendor prefixes at build time (happens automatically with your bundler)
  3. Stylelint with browser compatibility plugin — catch unsupported properties in CI before tests run
  4. Unit tests — verify component behavior
  5. Cross-browser Playwright tests — functional correctness across browsers
  6. Visual regression tests — catch rendering differences that pass functional tests

The Stylelint step is the cheapest feedback loop (seconds to run, runs in lint step) and catches the most systematic issues. Visual regression is the most comprehensive but also the most maintenance-intensive — start with Stylelint, add visual regression for your most visually complex components first.

Teams using HelpMeTest for cross-browser automation get the functional and visual testing layers through Playwright's multi-browser support, with test execution managed centrally rather than maintained per-project. The CSS static analysis layers (Stylelint, autoprefixer) live in your build pipeline regardless of your test infrastructure choice — they're build tools, not test tools.

The CSS compatibility landscape in 2024 is dramatically better than five years ago. The major browser engines have converged on most CSS features. But "most" is not "all," and the long tail of compatibility issues — particularly on older iOS Safari, which users don't update as aggressively as desktop browsers — remains a real source of production bugs. Automating the detection of these issues is substantially cheaper than discovering them in production.

Read more

Start now free