Why layout verification has to happen at real widths

Two defects survived multiple rounds of review on this site: an absolutely positioned header overlapping page content, and a navigation bar wrapping to two rows. Both were real, both were visible on any full-width desktop, and both were invisible to every check being run, because the only browser available had a fixed viewport of about 781 pixels.

The viewport is part of the test

A breakpoint is a conditional. A defect that exists inside one is not merely hard to see at another width: it does not exist there at all. Reporting it as "not reproducible" from a 781px pane is not a weak result, it is a result about a different layout entirely. The header collision began at 1200px and the nav wrap at 1200–1400px; neither is reachable from 781px under any amount of careful looking.

Measure geometry, do not look at it

Both defects were eventually found by comparing computed geometry against expectation. The header was `position: absolute`, so its height did not contribute to document flow, meaning the page's top padding had to clear it manually, and nothing failed when it stopped doing so. Measuring the gap between the header's bottom edge and the first content element's top edge, at every width, produces a negative number where the overlap is.

                      for (const width of [320, 375, 414, 768, 992, 1200, 1280, 1440, 1920]) {
  await page.setViewportSize({ width, height: 900 });

  const clearance = await page.evaluate(() => {
    const header = document.querySelector(".header-2");
    const first = document.querySelector("main h1, main .sys-hero");
    if (!header || !first) return null;

    // Negative means content starts behind the header: the defect.
    return Math.round(
      first.getBoundingClientRect().top - header.getBoundingClientRect().bottom,
    );
  });

  if (clearance !== null && clearance < 0) {
    throw new Error(`content overlaps header by ${-clearance}px at ${width}px`);
  }
}
                    

The important property is that this is an assertion. It has a pass condition, it runs at every width, and it fails loudly. A screenshot review has none of those, which is why the same defect returned after being fixed once.

Test the container against the content it frames

The navigation wrap had a subtler cause: two different container widths in the same layout. The page shell used one maximum width and the header used a framework container with stepped breakpoints. Below a certain width the shell was wider than the header by 134px, so the nav had less room than the content it sat above and wrapped. Nothing was wrong with the nav's own CSS, which is why it resisted investigation.

A useful check is to assert that a shared wrapper has the same computed width as the content it frames, at every breakpoint. Percentage alignment across mixed frameworks is a recurring source of defects because both values look plausible in isolation.

Disprove a suspected cause by removing it

When an element is flagged as causing horizontal overflow, the fastest way to know is to remove it and re-measure. If the number does not change, the element was not the cause regardless of how suspicious it looks. This is worth stating because the opposite method, inspecting the element, deciding it looks wrong, and fixing it, produces a fix with no evidence that it addressed anything, and the original fault remains.

The checklist that generalises

1. Enumerate the widths the layout actually has, from the breakpoints in the CSS.
2. Assert geometry (clearance, order, containment).
3. Include at least one width on each side of every breakpoint, plus the breakpoint itself.
4. Test in more than one engine; two of these defects were reported from Safari and reproduced in WebKit.
5. When something is suspected, remove it and re-measure.