How to Test Responsive UI Components

Test responsive UI components by exercising their meaningful states at widths that reflect the component’s actual layout transitions. Automate behavior and layout checks in a browser, inspect just-below and just-above breakpoint widths, include a narrow reflow check, and validate critical flows on physical mobile hardware. Device emulation is repeatable and useful, but it does not reproduce every property of a real phone.

This guide uses Playwright for browser automation and Chrome DevTools for breakpoint inspection. The same testing principles apply if your project uses another browser automation tool.

1. Choose component states and expected outcomes

Start with what the component does, not with a list of popular device models. A responsive card, navigation menu, table, or dialog may behave differently when it is empty, expanded, filled with long text, or showing a validation error. Select states that could change its layout or interaction.

Default and populated content.
Empty, loading, and error states when applicable.
Expanded and collapsed states for disclosure controls or navigation.
Long labels, unbroken strings, and large content sets that can expose overflow.
Interactive outcomes: buttons remain reachable, menus open and close, and keyboard focus remains usable.

For each state, write down an observable expected outcome: for example, the menu button is visible on a narrow viewport, activating it reveals navigation links, and those links fit in the viewport. Keep behavior assertions separate from visual comparisons so a screenshot difference does not obscure a functional regression.

2. Find the component’s actual breakpoints

Do not assume a universal phone, tablet, and desktop width set. Open the page in Chrome DevTools, enable Device Mode, and use the responsive viewport and media-query display to find the CSS transitions that affect the component. The breakpoint bars expose min-width and max-width media queries; change the viewport width to see when the layout switches. See the Chrome DevTools Device Mode guide.

For every transition that changes the component, test a width just below and just above it. Add representative narrow and wide widths that cover the content and layout risks. If a transition is at 768 CSS pixels, for example, inspect around 767 and 769 as well as your chosen narrow and wide cases. Those numbers illustrate the method; they are not a recommended universal breakpoint pair.

Viewport case	What it can reveal
Just below a breakpoint	Whether the compact layout works before the transition.
Just above a breakpoint	Whether the wider layout activates cleanly and avoids a gap or overlap.
Narrow viewport	Clipped content, horizontal overflow, unreachable controls, and wrapping problems.
Wide viewport	Unexpected stretching, alignment changes, or content that stops fitting its container.

3. Automate behavior and layout with Playwright

Playwright component tests mount components in a real browser, allowing tests to exercise browser layout and interactions. Playwright also supports visual regression workflows. Install the component testing package and browser for the framework you use by following the current Playwright component testing guide. The examples below use the current @playwright/experimental-ct-react package name only if installed according to that guide; older experimental component-testing packages have been removed, so use the current setup instructions for your framework and Playwright version.

For a page-level test, install Playwright Test and its browser binaries using the Playwright installation guide. Save the following as tests/responsive-card.spec.ts, adjust the page URL and selectors to match your app, then run npx playwright test.

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

const widths = [
  { name: 'narrow', width: 375, height: 812 },
  { name: 'just below breakpoint', width: 767, height: 900 },
  { name: 'just above breakpoint', width: 769, height: 900 },
  { name: 'wide', width: 1280, height: 900 },
];

test.describe('responsive product card', () => {
  for (const viewport of widths) {
    test(`${viewport.name}: content and actions remain usable`, async ({ page }) => {
      await page.setViewportSize({ width: viewport.width, height: viewport.height });
      await page.goto('http://localhost:3000/catalog');

      const card = page.getByTestId('product-card');
      await expect(card).toBeVisible();
      await expect(card.getByRole('heading', { name: 'Example product' })).toBeVisible();

      const detailsButton = card.getByRole('button', { name: 'Show details' });
      await expect(detailsButton).toBeVisible();
      await detailsButton.click();
      await expect(card.getByText('Product details')).toBeVisible();

      // Check the document for horizontal overflow at this viewport.
      const overflows = await page.evaluate(() =>
        document.documentElement.scrollWidth > document.documentElement.clientWidth
      );
      expect(overflows, 'page should not overflow horizontally').toBe(false);
    });
  }
});

The viewport dimensions here are illustrative. Replace them with your project’s actual breakpoint boundaries and supported content cases. Use stable test IDs or accessible roles and names; avoid selectors tied to incidental CSS class names. If a component test is a better fit than navigating a page, mount the component through the current Playwright component-testing setup and reuse the same viewport loop and assertions.

Use device descriptors selectively

Playwright device descriptors can provide a browser context with a selected user agent, screen size, viewport, and touch settings. They are useful when the component depends on touch behavior or user-agent-specific content, but they are not a complete inventory of devices and do not replace physical hardware checks. You can override the viewport after creating a context. Review the Playwright emulation documentation and browser documentation.

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

// The descriptor supplies device-like context defaults. Keep the viewport
// matrix deliberate and use a physical device for high-risk hardware checks.
test.use({ ...devices['iPhone 13'] });

test('touch navigation can be opened', async ({ page }) => {
  await page.goto('http://localhost:3000');
  await page.getByRole('button', { name: 'Open menu' }).tap();
  await expect(page.getByRole('navigation')).toBeVisible();
});

Use the browser projects your audience and risk justify. Playwright documents Chromium, Firefox, and WebKit projects, as well as branded Chrome and Edge channels. A Playwright WebKit run uses a WebKit build and should not be described as identical to shipping Safari. For cases where Safari-specific behavior matters, the Playwright documentation notes that WebKit on macOS is the closest available Safari experience within its browser setup.

4. Check reflow at a narrow width

Include a narrow layout check for content that normally scrolls vertically. WCAG 2.2 Success Criterion 1.4.10 Reflow specifies a width equivalent to 320 CSS pixels for vertically scrolling content and a height equivalent to 256 CSS pixels for horizontally scrolling content, with exceptions for content whose use or meaning requires a two-dimensional layout. The goal is that content remains available without requiring two-dimensional scrolling within the criterion’s scope. Read the W3C WCAG 2.2 Reflow criterion.

A 320 CSS pixel check is one reflow check, not a complete accessibility audit or proof of WCAG conformance. Review the component’s purpose and applicable exceptions, and assess other accessibility requirements separately.

5. Validate critical behavior on real devices

Use emulation for fast, repeatable checks, then use a physical phone or tablet when the flow is important or a device-specific issue is plausible. Chrome documents that some mobile aspects cannot be simulated and recommends testing on an actual mobile device when uncertain; see Device Mode’s limitations and testing guidance.

Prioritize hardware checks for touch targets and gestures, mobile keyboard and viewport behavior, device-specific rendering, and high-risk user journeys such as checkout or account access. A manual device check complements automation: it can catch hardware behavior that emulation misses, while automation makes the same state and viewport checks repeatable.

6. Keep the viewport matrix useful

A practical matrix covers each meaningful layout transition and each component state with a manageable set of browser contexts. Avoid multiplying every state by every named device unless a specific risk calls for it. You can run a small representative suite on each relevant browser engine, then add focused cases for platform-specific behavior.

Cover the actual CSS transitions rather than relying only on device presets.
Test near both sides of a breakpoint, not only at a conventional device width.
Use representative narrow and wide widths plus content that stresses wrapping and overflow.
Run the browser engines relevant to your users and application risks.
Reserve physical-device checks for high-risk flows and issues that depend on real hardware.

Choose between automated assertions, visual comparison, DevTools inspection, and hardware checks based on the failure you want to catch. Assertions are suited to interaction and content outcomes; visual comparison can flag rendering changes; DevTools helps locate transitions; real devices check physical behavior. These methods complement each other and are not interchangeable measures of accessibility or browser fidelity.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request captures a page as PNG, JPEG, WebP, or PDF. For example, capture a page at a target viewport by adding the viewport parameters supported by the ScreenshotNeo API documentation:

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com \
  -d width=375 \
  -d height=812 \
  -o responsive-check.webp

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Screenshots can help you inspect rendered output, but they do not replace interactive Playwright tests or real-device checks. Sign up for 1,000 free screenshots a month with no card.

Troubleshooting

Symptom	Likely cause	Fix
The test passes at common widths but fails around a transition.	The matrix tests only representative device sizes and skips the CSS breakpoint boundary.	Inspect media queries in DevTools and add widths just below and just above each component-relevant transition.
A control is visible but cannot be activated in automation.	The control may be covered, disabled, offscreen, or configured for touch-only interaction.	Assert its state and visibility, inspect overlays and stacking, scroll it into view if appropriate, and use a touch context only when touch behavior is part of the requirement.
The narrow test reports horizontal overflow.	A fixed-width child, long unbroken text, image, or intentionally two-dimensional region may exceed the viewport.	Find the overflowing element, allow appropriate wrapping or sizing, constrain media to its container, or document and validate a legitimate two-dimensional exception.
A screenshot comparison changes across runs.	Dynamic content, animation, time, fonts, network-loaded assets, or browser differences may change pixels.	Stabilize test data and animation, wait for the relevant content or font readiness, and keep comparisons within a consistent browser and environment.
Mobile emulation looks correct but a phone behaves differently.	Emulation cannot reproduce every mobile hardware or browser property.	Reproduce the flow on the affected hardware and treat the emulated result as a useful diagnostic, not final proof.
A WebKit test is mistaken for a Safari guarantee.	Playwright WebKit is not the branded Safari browser.	Use the documented WebKit coverage appropriately and verify Safari-sensitive behavior in the closest relevant environment and on hardware when needed.

Performance, reliability, and cost

Browser coverage costs time in proportion to the number of states, viewport cases, and browser projects you run. Keep the default suite focused on meaningful states and breakpoint boundaries; add more contexts where a user impact or known platform risk justifies them. Reuse deterministic data and avoid waiting for unrelated network activity when the test only needs a specific component state.

For reliability, make the test wait for observable readiness, use stable selectors, and assert outcomes rather than implementation details. A layout check at one width can miss a nearby transition, while a screenshot alone cannot establish that controls work. Browser automation is repeatable within its configured environment; physical-device validation adds realism at the cost of requiring access to the relevant hardware.

The core DIY workflow uses browser tooling and test code. The sources do not establish a universal performance benchmark or a required physical-device model, so select coverage based on your application, supported browsers, and risk rather than an unsupported numeric target.

FAQ

Should every component be tested at every device size?

No. Cover its meaningful states and the widths where its layout changes, then add cases for specific risks such as long content or touch interaction.

Is a screenshot test enough to prove a responsive component works?

No. A screenshot can reveal visual differences, but interaction and content availability need behavioral checks too.

Does a 320 CSS pixel check prove accessibility?

No. It addresses the width condition in WCAG’s Reflow criterion for relevant content; it is not a full accessibility evaluation.

When should I use a physical phone?

Use one when a flow is high risk, behavior depends on hardware, or emulation leaves a device-specific question unresolved.