Systematically Testing Responsive Breakpoints

1. Why breakpoint tests shouldn't target every pixel

A common misconception in responsive testing is that you need to check as many viewport widths as possible to be safe. In practice, this leads to test suites that iterate over 320px, 375px, 414px, 480px, 600px, 768px, 900px, 1024px, and a dozen more widths, even though the layout doesn't change between most of them at all. Every additional viewport width costs CI runtime without adding any extra signal, as long as no CSS rule changes between two widths.

What actually matters are the widths where the layout genuinely changes, in other words exactly the breakpoints defined in the Tailwind design system as sm, md, lg, and xl. Everything between two breakpoints behaves identically at the CSS level, because Tailwind utilities like md:grid-cols-3 only kick in exactly at the defined threshold. Once you understand this, you can drastically reduce the number of required test runs and focus the remaining test time on the spots where bugs can actually occur.

2. Deriving the relevant breakpoints from the design system

The first step of any systematic breakpoint test strategy is reading the actual thresholds out of the configuration instead of guessing them from experience. In Tailwind CSS v4's CSS-first approach, breakpoints are defined via @theme using named --breakpoint-* variables, no longer necessarily in a separate tailwind.config.js. These values are the single binding source: any test that invents its own width values is testing past the actual design system.

In a Hyvä theme, it pays off to export the effective breakpoint values once into a central test configuration, for example as a JSON or JS object imported by both Cypress and Playwright specs. That keeps the test suite automatically in sync whenever a breakpoint moves in the design system, instead of maintaining width values twice and letting them drift out of sync. A single changed value in the central configuration then updates every affected test case automatically.

/* app/design/frontend/Mironsoft/default/web/tailwind/tailwind-source.css */
@theme {
  /* Named breakpoints - single source of truth for the design system */
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;
}

/* Export the same values as JSON for Cypress/Playwright to import,
   generated once via a small build script, never hand-copied. */

3. Boundary testing: just above and below the threshold

Most layout bugs at breakpoints are classic off-by-one mistakes: a Tailwind md: prefix applies from 768px inclusive, not only from 769px. If you only test at exactly 768px, or only halfway between two breakpoints, you'll miss exactly the cases where a developer wrote max-width: 767px instead of max-width: 768px in a media query, or where an additional CSS framework collides with a differing convention.

The robust boundary testing pattern therefore always checks three points per breakpoint: one pixel below the threshold, exactly at the threshold, and one pixel above it. For an md breakpoint of 768px that means concrete tests at 767px, 768px, and 769px. Only this approach reliably proves that the layout switch happens exactly where expected, rather than one or more pixels off, which happens quickly with nested media queries in particular.

4. Breakpoint iteration with Cypress

Cypress offers cy.viewport(width, height) as a direct way to change the viewport size inside a test. For systematic breakpoint testing, iterate over an array of the relevant breakpoints and run the same test logic for each entry, instead of duplicating a separate it() definition per width. This keeps the test suite maintainable, even when another breakpoint gets added later.

It's important to briefly wait after each cy.viewport() call, or check for a stable DOM element, before assertions run, since CSS transitions and reflow calculations don't finish synchronously with the viewport change. Cypress runs tests in a single browser window by default, which makes the viewport change very fast. For genuine cross-browser coverage, the same test structure should additionally run in Firefox and WebKit via the corresponding Cypress browser launchers.

// cypress/e2e/responsive/breakpoints.cy.js
// Single source of truth, mirrors the Tailwind @theme breakpoint values
const breakpoints = [
  { name: 'sm', width: 640 },
  { name: 'md', width: 768 },
  { name: 'lg', width: 1024 },
  { name: 'xl', width: 1280 },
];

describe('Product grid across breakpoints', () => {
  breakpoints.forEach(({ name, width }) => {
    it(`renders a valid grid layout at ${name} (${width}px)`, () => {
      cy.viewport(width, 900);
      cy.visit('/catalog/category/view/id/23');

      // Let CSS transitions and reflow settle before asserting
      cy.get('[data-testid="product-grid"]').should('be.visible');
      cy.get('[data-testid="product-card"]').should('have.length.greaterThan', 0);
    });
  });
});

5. Breakpoint iteration with Playwright

Playwright sets viewport sizes via page.setViewportSize() or directly when creating a new BrowserContext with the viewport option. The decisive advantage over Cypress is native parallelization: multiple breakpoints can run simultaneously instead of sequentially via Playwright's test.describe.parallel() or via separate projects in playwright.config.ts, which noticeably reduces the total runtime of a breakpoint matrix.

For boundary tests, a parameterized test function works well, receiving both the breakpoint list from the central design system configuration and the one-pixel delta value as parameters. Playwright's built-in toHaveScreenshot() assertion is also excellent for triggering a screenshot comparison at each boundary test, catching not just structural but also purely visual regressions right at the breakpoint boundary.

// tests/responsive/breakpoint-boundaries.spec.ts
import { test, expect } from '@playwright/test';

// Mirrors the Tailwind @theme breakpoint values, single source of truth
const mdBreakpoint = 768;
const deltas = [-1, 0, 1];

for (const delta of deltas) {
  const width = mdBreakpoint + delta;

  test(`navigation state at ${width}px (md boundary ${delta})`, async ({ page }) => {
    await page.setViewportSize({ width, height: 900 });
    await page.goto('/');

    const isDesktopNav = width >= mdBreakpoint;
    const mobileToggle = page.getByTestId('nav-mobile-toggle');
    const desktopNav = page.getByTestId('nav-desktop');

    if (isDesktopNav) {
      await expect(desktopNav).toBeVisible();
      await expect(mobileToggle).toBeHidden();
    } else {
      await expect(mobileToggle).toBeVisible();
      await expect(desktopNav).toBeHidden();
    }
  });
}

6. Detecting content reflow and element overlap

A breakpoint transition can trigger two distinct bug classes: unexpected content reflow, where text suddenly gets cut off or elements land outside the visible area, and element overlap, where two normally separate elements overlap because a width or margin value wasn't adjusted for the new column count. Both bug classes are only partially detectable with plain snapshot comparisons, because small pixel shifts are often flagged as false positives.

A more reliable approach combines getBoundingClientRect() queries for all relevant elements with a simple overlap calculation that checks whether two bounding boxes mathematically intersect. For content reflow, also compare scrollWidth against a container's clientWidth. A mismatch indicates horizontal overflow, which is almost always a bug on mobile breakpoints. These checks work well as a reusable helper function in both frameworks.

// tests/support/reflow-helpers.ts
// Detects horizontal overflow and overlapping elements at a given viewport
export async function detectReflowIssues(page) {
  return page.evaluate(() => {
    const issues = [];
    const container = document.querySelector('[data-testid="product-grid"]');

    if (container && container.scrollWidth > container.clientWidth + 1) {
      issues.push(`Horizontal overflow: scrollWidth ${container.scrollWidth} > clientWidth ${container.clientWidth}`);
    }

    const cards = Array.from(document.querySelectorAll('[data-testid="product-card"]'));
    const rects = cards.map((el) => el.getBoundingClientRect());

    for (let i = 0; i < rects.length; i++) {
      for (let j = i + 1; j < rects.length; j++) {
        const a = rects[i];
        const b = rects[j];
        const overlaps = a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
        if (overlaps) {
          issues.push(`Card ${i} overlaps card ${j}`);
        }
      }
    }

    return issues;
  });
}

7. Navigation: testing the hamburger-to-full-menu transition

The switch from a hamburger navigation to the full desktop navigation is one of the most common, and simultaneously worst-tested, breakpoint transitions in Hyvä themes. Typical bugs: the hamburger icon stays visible one pixel width too long and overlaps the appearing desktop navigation, or a dropdown submenu still opens in the mobile overlay style after the switch instead of as a desktop flyout.

A robust test checks at the exact breakpoint boundary, via cy.get() or page.locator(), that exactly one of the two navigation elements is visible, never both at once and never neither. It's also worth adding a click test right at the boundary: does the mobile navigation open correctly as an Alpine.js overlay at 767px, and is the desktop navigation clickable without an overlay at 768px instead? This interaction layer catches bugs that a plain visibility check would miss.

8. Product grid: verifying the column count switch

Product listings are another breakpoint hotspot, because the grid column count in Hyvä stores typically changes several times: two columns on mobile, three on tablet, four on desktop. A common bug appears when grid-cols-2, md:grid-cols-3, and lg:grid-cols-4 are set correctly, but a single product card element carries a fixed min-width that no longer fits the available width at three columns and wraps as a result.

The most reliable test doesn't count CSS classes, it checks the actually rendered position of the product cards: cards with an identical offsetTop position belong to the same row, and their count matches the expected column count. This check works regardless of whether the grid is implemented with CSS Grid, flexbox, or Tailwind utilities, and reliably catches a card slipping into the wrong row due to faulty wrapping, a bug that stays invisible in a plain class-name check.

9. Naive vs. systematic approach compared

The difference between a random list of widths and a systematic breakpoint boundary strategy shows most clearly in a direct comparison, both in CI runtime and in actual bug detection rate. The table below compares both approaches across the most important testing dimensions.

In practice, the systematic variant finds more real bugs despite far fewer test runs, because it targets exactly where layout changes happen. Teams that switch from an arbitrary width list to boundary testing often cut their CI runtime for responsive tests by 60 to 70 percent, without sacrificing coverage of the transitions that actually matter.

# .github/workflows/responsive-breakpoints.yml
name: Responsive Breakpoint Tests
on: [pull_request]

jobs:
  breakpoint-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        breakpoint:
          - { name: sm, width: 640 }
          - { name: md, width: 768 }
          - { name: lg, width: 1024 }
          - { name: xl, width: 1280 }
        delta: [-1, 0, 1]
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - name: Run boundary tests for ${{ matrix.breakpoint.name }} (${{ matrix.delta }}px)
        run: >
          npx playwright test tests/responsive/breakpoint-boundaries.spec.ts
          --grep "${{ matrix.breakpoint.name }} boundary ${{ matrix.delta }}"
        env:
          BREAKPOINT_WIDTH: ${{ matrix.breakpoint.width }}
          BREAKPOINT_DELTA: ${{ matrix.delta }}

10. Summary

Systematic breakpoint testing solves a simple but expensive problem: randomly trying viewport widths wastes CI time and still misses the spots where bugs actually happen. What matters are only the widths defined in the Tailwind design system as sm, md, lg, and xl, and specifically the three points right at each boundary: one pixel below, exactly at the threshold, and one pixel above. That's exactly where off-by-one errors hide, errors that can never occur between two breakpoints.

Cypress and Playwright both offer direct APIs for viewport control, with Playwright additionally providing native parallelization for larger breakpoint matrices. Combined with targeted checks for content reflow, element overlap, navigation transitions, and grid column count, the result is a test suite that needs far fewer runs than an arbitrary width list while still catching more real layout bugs. Organized as a breakpoint matrix in a CI pipeline, this coverage stays maintainable even as the design system grows.

11. FAQ: Systematically Testing Responsive Breakpoints