Applitools Visual Tests for Responsive Website Breakpoints

To test responsive website breakpoints with Applitools, derive viewport widths from your own CSS and design requirements, then run visual checkpoints at fixed sizes on both sides of important transitions. With Playwright, configure a deterministic viewport for each test, wait for the page to reach the state you want to inspect, and call eyes.check(). Review visual differences before accepting a new baseline.

There is no universal breakpoint list that fits every site. A useful test plan targets the widths where your layout changes, plus nearby widths that can expose wrapping, overflow, or a navigation collapse happening too early or too late. Applitools describes its responsive testing as supporting multiple mobile, tablet, and desktop views in one test; the exact setup depends on your SDK and runner. See the Applitools responsive design testing overview and the Playwright integration documentation.

1. Find the breakpoints that matter

Start with the application rather than a generic phone/tablet/desktop preset. A breakpoint is relevant when the design or CSS changes behavior there: a navigation bar collapses, columns stack, a grid changes column count, spacing changes, or a component switches presentation.

Search the application styles for media queries and responsive component rules.
Check design specifications and component documentation for intended transitions.
List each meaningful transition width. Add test widths immediately below and above it when a one-pixel boundary or nearby wrapping behavior matters.
Include representative widths within each range if the layout can still break away from the transition itself.
Choose a fixed height as well as a width. Keep browser, operating system, device scale, and other environment details stable when you compare against the same baseline.

For a transition at width B, a small boundary pair is typically B - 1 and B (or B and B + 1 if the CSS uses a min-width query). Add a normal in-range width when the component has behavior that changes gradually. This is a test design pattern, not an Applitools-prescribed pixel standard.

What to verify	Useful viewport choice	Example failure to look for
Media-query transition	Just below and at/above the actual CSS threshold	Wrong navigation state or a column that has not stacked
Text and controls near wrapping limits	A width near the smallest supported width in that layout range	Clipped button text, overlapping labels, or horizontal scroll
Page-level composition	A representative width for each supported layout range	Unexpected gaps, squeezed content, or inconsistent alignment
Cross-browser behavior	The same deliberate width across the browser engines you support	Different font metrics or browser-specific wrapping

2. Install and configure Playwright with Applitools

The example below uses the Applitools-enhanced Playwright fixture documented by Applitools. It assumes a JavaScript project with Playwright Test already set up and an APPLITOOLS_API_KEY environment variable configured in your shell or CI secret store. Install the integration package using the package manager for the project:

npm install --save-dev @playwright/test @applitools/eyes-playwright
npx playwright install

Set the site origin through an environment variable so the same test can run against local, preview, and staging environments:

export BASE_URL="http://127.0.0.1:3000"
export APPLITOOLS_API_KEY="YOUR_APPLITOOLS_API_KEY"

Do not commit real API keys. Configure the key as a protected CI secret. Create a Playwright config such as playwright.config.ts:

import { defineConfig } from '@playwright/test';
import { EyesFixture } from '@applitools/eyes-playwright/fixture';

export default defineConfig<EyesFixture>({
  testDir: './tests',
  use: {
    baseURL: process.env.BASE_URL ?? 'http://127.0.0.1:3000',
    // A fixed default helps tests that do not override the viewport.
    viewport: { width: 1280, height: 800 },
    eyesConfig: {
      appName: 'Storefront',
      // Choose when visual diffs should fail the Playwright test.
      failTestsOnDiff: 'afterEach',
    },
  },
});

Playwright supports viewport configuration in its use settings and at test scope; its default is a consistent 1280 by 720 viewport unless overridden. See the Playwright configuration guide. The Applitools fixture and options can evolve, so check the current Applitools Playwright integration guide if your installed SDK differs.

3. Write a boundary-focused visual test

This complete test runs one checkpoint per explicitly selected width. Replace the illustrative widths with values from your CSS and design rules. The sample uses a fictional local storefront route; change /products to a page in your application and make sure the test data is stable.

// tests/responsive-breakpoints.spec.ts
import { test } from '@applitools/eyes-playwright/fixture';

const viewports = [
  // Example only: replace 768 with a breakpoint from your own styles.
  { name: 'just-below-tablet-transition', width: 767, height: 900 },
  { name: 'tablet-transition', width: 768, height: 900 },
  { name: 'just-above-tablet-transition', width: 769, height: 900 },
  // Add your other real breakpoint boundaries and representative widths.
  { name: 'wide-desktop', width: 1440, height: 1000 },
];

for (const viewport of viewports) {
  test(`products layout: ${viewport.name}`, async ({ page, eyes }) => {
    await page.setViewportSize({
      width: viewport.width,
      height: viewport.height,
    });

    await page.goto('/products', { waitUntil: 'networkidle' });
    await page.getByRole('heading', { name: 'Products' }).waitFor();

    // Add app-specific setup here: stable data, dismissed onboarding,
    // selected locale, or a known authenticated state.
    await eyes.check(`Products - ${viewport.name}`, {
      fully: true,
      matchLevel: 'Strict',
    });
  });
}

Run the test with:

npx playwright test tests/responsive-breakpoints.spec.ts

The test sets both viewport dimensions before navigation and records the width in its test and checkpoint names. Clear names make it easier to identify which breakpoint produced a difference. If your page makes long-polling or analytics requests that prevent networkidle, wait on an application-specific ready signal instead, such as a heading, skeleton removal, or a test-only readiness attribute.

4. Choose the right checkpoint and match level

Full page or focused component?

Full page: use fully: true when the responsive behavior below the fold matters, including stacked sections, sticky elements, or page-wide overflow.
Focused region: pass a locator as region when the question is about one component, such as a responsive navigation bar or product card. This keeps the checkpoint focused and easier to review.
Ignored region: use ignoreRegions only for content whose visual change is irrelevant to the test. Ignoring a region also means you will not catch layout defects inside it.
Floating region: use a floating region for an element allowed to move within defined limits while its appearance remains relevant. Consult the SDK reference for the installed version’s exact API.

Applitools documents full-page checks, element or region capture, match levels, and ignored regions for Playwright in its integration guide.

Strict versus Layout

Match level	What it checks	Use it when	Tradeoff
`Strict`	Visible appearance such as text, fonts, colors, graphics, and element positions, while aiming to ignore rendering variation that is not perceptible.	You want a regression check for a mostly static page in a specified browser and operating system.	Dynamic content or environment differences may need test data control, a narrower region, or explicit handling.
`Layout`	Presence and relative arrangement of elements; content and styling differences receive less emphasis.	Content is dynamic, localized, or compared across environments, and the key requirement is that the layout remains sound.	It is less suited to catching a color, font, or text-style regression by itself.

Applitools documents these distinctions in its match-level guidance. For breakpoint work, Layout can help compare structure across different sizes, while Strict is useful when each viewport has a known expected appearance. Consider separate checks if both layout integrity and styling matter; do not assume a Layout check validates color or typography.

5. Review baselines instead of auto-accepting changes

A baseline is the approved visual reference for a checkpoint. When a run reports a difference, inspect the baseline and new rendering side by side, then decide whether the change is an intended design update or a defect. Accept a new baseline only after that review. A baseline update records approval of the new expected rendering; it does not establish by itself that the design is correct.

For every changed breakpoint, check the actual responsive behavior: whether the expected navigation is visible, columns change at the intended width, content remains readable, and no horizontal overflow or overlap appears. Keep checkpoint names tied to route and viewport so baseline review is actionable. Applitools describes visual testing as capturing checkpoints, comparing them with stored baselines, and having a team review differences before accepting or rejecting them; see its Eyes overview.

6. Expand viewport and browser coverage carefully

Begin with widths around real transitions and add the browser engines and operating systems your users and support policy require. Testing several widths in one browser can find breakpoint logic defects, but it does not replace cross-browser checks: font metrics and rendering may differ between environments.

Applitools says its Ultrafast Grid can render captured application states across browser and viewport combinations in parallel, and its responsive product page describes multiple responsive views in one test. These are vendor-described capabilities, not a speed guarantee for a particular suite. See the responsive design page and the test execution overview.

Keep the matrix purposeful. Each extra viewport and browser environment can add visual results to triage. Add cases because they cover a transition, supported environment, or known risk, rather than collecting device sizes without a test question. Record browser, OS, viewport, locale, and color scheme when diagnosing a baseline mismatch.

7. Troubleshooting

Symptom	Likely cause	Fix
The screenshot is the wrong size or the breakpoint state is unexpected.	A different viewport is being applied by the test config, a project setting, or code after initial setup.	Set the viewport explicitly for the test before navigation, check for later `setViewportSize` calls, and inspect `window.innerWidth` at the checkpoint.
Why does my test fail to set the viewport size?	Applitools’ older Selenium/Appium support guidance says Eyes viewport sizing refers to the browser’s inner content area; the required outer window can exceed the available display, or the requested size may be below browser minimums. It also notes Appium mobile windows are already maximized and Windows display scaling can affect sizing calculations.	Confirm the runner has enough display area, try a supported viewport, and check whether your setup is Selenium/Appium-specific. For Appium, follow the current mobile SDK guidance instead of forcing a desktop viewport. The cited Applitools support article dates from 2019, so verify behavior against your current SDK and runner.
The page sometimes captures before content is ready.	Network idle may be delayed by polling, analytics, or long-lived connections, or the app’s data request finishes after navigation.	Wait for a reliable application signal or deterministic test fixture before `eyes.check()`. Avoid arbitrary sleeps unless the page genuinely requires a known delay.
Visual diffs appear on every run although the layout looks unchanged.	Time-dependent text, randomized content, advertisements, animations, or changing data creates nondeterministic pixels.	Stabilize test data and time where possible. Disable motion for the test if appropriate, wait for transitions to finish, or ignore only the specific region whose content is intentionally irrelevant.
A page-level comparison flags a harmless widget while missing the component you care about.	The checkpoint scope or match level does not match the test question.	Capture the target locator as a region, use Strict where styling matters, and reserve ignored regions for explicitly out-of-scope content.
One viewport passes but text overlaps at an adjacent width.	The test matrix covers representative device categories but misses the CSS transition or a narrow content constraint.	Add widths immediately around the actual media-query boundary and the smallest supported width. Inspect computed styles and horizontal overflow at those sizes.
A difference appears after accepting a baseline.	The approved reference changed, or the new baseline was accepted before the responsive behavior was fully reviewed.	Review the change in the dashboard and source control, confirm each affected viewport, and restore or replace the baseline only after the expected design is established.

Applitools’ viewport-sizing advice cited above is specifically about Selenium/Appium and is older. For Playwright, configure the viewport through Playwright’s context/test options and verify the actual inner page dimensions; do not assume the Selenium sizing mechanism applies unchanged.

8. Performance, reliability, and cost considerations

Reduce unnecessary cases: cover real transitions and supported environments. A well-chosen matrix is easier to review than a large collection of redundant widths.
Keep captures deterministic: use stable data, fixed dimensions, known locale and color scheme, and a clear ready condition. This reduces noise and makes a diff easier to interpret.
Choose checkpoint scope deliberately: full-page capture can reveal lower-page layout defects but includes more content; region capture narrows review to a component.
Use parallel rendering when appropriate: Applitools describes Ultrafast Grid as a way to render across browser and viewport combinations in parallel. Actual time and cost depend on your plan, configuration, and workload; consult current vendor terms rather than assuming a benchmark.
Plan review ownership: visual testing creates differences that need a human decision when the intended design changes. Assign responsibility for baseline review as part of the change workflow.
Do not treat a passing visual check as full functional coverage: visual checkpoints tell you about appearance. Keep interaction and semantic assertions for behavior that cannot be established by a screenshot.

Or skip the browser setup

If you need a clean screenshot for a page without creating and maintaining browser automation, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One GET request returns an image or PDF. For a screenshot capture, call the API with your page URL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

See the ScreenshotNeo API documentation for request options and response details. Cookie banners are accepted like a visitor and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before the shot; each of these steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

How do I test responsive breakpoints with Applitools?

Identify the breakpoints in your own CSS and design requirements, choose fixed widths around important transitions, set a fixed height, wait for a stable page state, and make named Eyes checkpoints at each size. Review diffs before approving a baseline.

Should I use full-page screenshots for every breakpoint?

Use full-page capture when below-the-fold layout matters. For a single responsive component, a region checkpoint can make the result more focused and faster to review.

Is Layout match enough to validate a responsive page?

Layout is useful for element presence and relative arrangement, especially with dynamic content or cross-environment comparison. Use Strict or additional checks when colors, typography, or other visual styling must also match.

Do I need a separate test for every browser width?

You need explicit coverage for meaningful breakpoint boundaries and supported environments. Applitools documents multi-viewport responsive workflows, but select widths based on your application’s actual transitions and risks.