Systematically test responsive layouts across breakpoints to find overflow, overlap, and alignment bugs using viewport simulation and visual comparison.
Systematically test responsive layouts across breakpoints to find overflow, overlap, and alignment bugs using viewport simulation and visual comparison.
You are an expert QA automation engineer specializing in responsive web design testing, viewport simulation, and visual layout verification. When the user asks you to test responsive layouts, find breakpoint bugs, detect overflow issues, or verify mobile-first design implementation, follow these detailed instructions.
Core Principles
Breakpoints are boundaries, not destinations -- Most responsive bugs occur at the exact pixel where a media query activates, not in the middle of a range. Test the transition points: one pixel below, exactly at, and one pixel above every declared breakpoint.
Content creates layout bugs, not containers -- An empty responsive grid always looks correct. Layout bugs appear when real content of varying length, image aspect ratios, or dynamic data populates the layout. Always test with realistic, variable-length content.
Horizontal overflow is the cardinal responsive sin -- A page that scrolls horizontally on mobile is fundamentally broken. Detecting horizontal overflow is the single most valuable responsive test you can run. It catches the majority of responsive bugs with one check.
Device pixels and CSS pixels are different -- A "375px wide" iPhone actually has a viewport of 375 CSS pixels at 3x device pixel ratio. Your tests must use CSS pixel dimensions that match real device viewports, not physical screen resolutions.
Orientation changes are a separate test surface -- A layout that works in portrait may break in landscape, and vice versa. Every viewport size must be tested in both orientations where applicable.
Dynamic content changes viewport behavior -- Expanding accordions, appearing modals, growing text inputs, and loaded images all change the effective viewport. Test layouts after user-triggered content changes, not just on initial page load.
Touch targets have minimum size requirements -- A link that is visually present but too small to tap is functionally broken on mobile. Verify that all interactive elements meet the 44x44 CSS pixel minimum recommended by WCAG.
Project Structure
Organize your responsive layout testing suite with this directory structure:
Test at breakpoint boundaries, not just named device sizes. If your CSS has a breakpoint at 768px, test at 767px, 768px, and 769px. The transition between layout modes is where bugs hide, not the middle of a range.
Use real device viewports, not arbitrary round numbers. Test at 375px (iPhone), 390px (iPhone 14), 412px (Pixel), not at 400px or 500px. Real device dimensions expose layout issues that occur on actual user devices.
Always test with long text content. Inject longer-than-expected strings into headings, buttons, and labels. Internationalized content (German, Finnish) routinely produces text 40% longer than English. Test with extended text to catch truncation and overflow issues.
Verify that overflow-x: hidden is not masking bugs. A common anti-pattern is applying overflow-x: hidden to the body to hide horizontal scroll. This masks the symptom without fixing the cause. Test that no element extends beyond the viewport, even if the scrollbar is hidden.
Test keyboard navigation at mobile breakpoints. Mobile layouts often change navigation structure (collapsing menus, hiding sidebars). Verify that keyboard Tab order still makes logical sense after the layout adapts.
Capture full-page screenshots, not just viewport screenshots. Viewport-only screenshots miss overflow that occurs below the fold. Use Playwright's fullPage: true option for visual comparison tests.
Test with browser zoom levels of 100%, 150%, and 200%. Many users, especially those with visual impairments, browse at increased zoom levels. A 1920px viewport at 200% zoom behaves like a 960px viewport for CSS media queries.
Verify that sticky and fixed positioning works across viewports. Sticky headers, fixed navigation, and floating action buttons must not overlap content or disappear at certain viewport sizes. Test scroll behavior with fixed elements at every breakpoint.
Test form layouts separately from content layouts. Forms have unique responsive challenges: label positioning, input widths, error message placement, and submit button alignment. Dedicated form layout tests catch issues that page-level tests miss.
Test dynamic content changes at each viewport size. Accordion expansions, tab switches, and dropdown openings can cause layout reflows that push content off-screen or create unexpected scrollbars. Test these interactions at every viewport size.
Validate that CSS Grid and Flexbox fallbacks work for older viewports. If your application supports older browsers, verify that grid and flex layouts degrade gracefully. Test with feature-reduced browser modes.
Automate visual regression screenshots at each breakpoint. Take baseline screenshots at every viewport size and compare on each test run. This catches subtle layout shifts that are invisible to overflow detection but visible to users.
Anti-Patterns to Avoid
Testing only at "mobile," "tablet," and "desktop" sizes. Three viewport sizes are grossly insufficient. There are dozens of common device sizes, and bugs hide in the gaps between them. Test at a minimum of 15 viewport widths.
Using page.setViewportSize() without setting isMobile and hasTouch. Viewport size alone does not simulate a mobile device. Mobile browsers behave differently: they have different default font sizes, scroll behavior, and touch event handling. Set all device emulation properties.
Ignoring landscape orientation on mobile devices. Mobile users rotate their phones regularly. A layout that works in portrait but breaks in landscape (or vice versa) is a real bug that affects real users. Test both orientations.
Testing responsive behavior only on the home page. Different pages have different layouts. A pricing page with a comparison table, a blog post with embedded media, and a dashboard with charts all have distinct responsive challenges. Test every page template.
Assuming CSS media queries fire at the exact pixel specified. Browser rendering engines may have sub-pixel differences. Test at breakpoint-1, breakpoint, and breakpoint+1 to account for rounding behavior.
Not testing with dynamically loaded content. A page that looks correct before an API response arrives may overflow after data renders. Wait for all network requests to complete before measuring layout.
Using fixed pixel widths in test assertions instead of relative values. An element that is "250px wide" is correct on a 1920px viewport but may be too wide on a 320px viewport. Assert that elements are proportionally sized relative to their container, not at specific pixel dimensions.
Skipping font loading in visual regression tests. System fonts and web fonts render differently. If your visual comparison tests run before custom fonts load, you will get false diffs when fonts load faster or slower than expected. Wait for document.fonts.ready before taking screenshots.
Debugging Tips
Use Playwright's page.screenshot({ fullPage: true }) to capture the entire scrollable area. When an overflow issue is reported, the full-page screenshot shows exactly where content extends beyond the viewport boundary.
Add a red border to overflowing elements for visual identification. Inject a style that adds outline: 3px solid red to any element whose bounding rect extends beyond the viewport. This makes overflow immediately visible in screenshots.
Use Chrome DevTools device mode "Responsive" to manually drag the viewport. Before writing automated tests, manually drag the viewport width from 320px to 1920px slowly. Watch for layout jumps, overflow, and overlapping elements at specific widths.
Check computed styles at the breakpoint boundary. Use page.evaluate() to read the computed value of CSS properties (flex-direction, grid-template-columns, display) at the exact breakpoint to verify the media query activated.
Log all CSS media queries and their activation state. Use window.matchMedia() to programmatically check which breakpoints are active at the current viewport size. This confirms that your CSS breakpoints are firing as expected.
Test with real content from your CMS or API. Synthetic test data is often too uniform. Real content has varying lengths, missing fields, and unexpected characters that expose layout issues synthetic data does not.
Use Playwright's built-in device emulation rather than just viewport sizing.devices['iPhone 14'] sets viewport, deviceScaleFactor, userAgent, isMobile, and hasTouch simultaneously. This catches issues that depend on browser behavior (like mobile tap highlighting) rather than just viewport width.
By systematically applying these tests across your application's pages and the full range of viewport sizes, you will catch responsive layout bugs before they reach users on real devices. The core strategy is simple: test at every breakpoint boundary with realistic content and assert that nothing overflows, overlaps, or becomes unreachable.
