Skip to content
Saimul Islam

viewport-qa: responsive design testing with numbers, from 390 to 3840

Responsive design testing that measures the layout at every viewport width: overflow, clipping, inconsistent insets and radii, low-resolution images and layout shift.

Install
npm install viewport-qa playwright
npx playwright install chromium

Overview

viewport-qa loads a page in Chromium at each viewport width and measures the layout: horizontal overflow, clipped text, elements off-screen, images shown above their resolution, repeated images, layout shift, edge-touching bands, inconsistent insets and radii, and orphan grid rows.

Every finding comes with a check id, a severity, a selector, the width and the numbers that triggered it. axe and Lighthouse check accessibility and performance, and visual-regression tools compare screenshots; none of them measures whether a layout stays consistent from phone to 4K. It runs on Playwright, from the command line or inside your own tests.

Examples

Test a page at two widths
viewport-qa overflow.html --widths 390,1440
Sample output
viewport-qa  overflow.html

390x844 @2x  1 error, 2 warnings
  error    horizontal-overflow  html
           Page scrolls sideways: scrollWidth 924px against a 390px viewport (534px too wide).
  warning  offscreen-element  div.wide
           Element runs 534px past the right edge (left 24, right 924, viewport 390).
  warning  edge-touching  div.wide
           Box (#fee2e2) touches the right edge of the viewport: left 24px, right -534px.

1440x900 @2x  no problems

1 error, 2 warnings across 2 widths.
Check a URL from code
import { checkUrl, hasProblems } from 'viewport-qa';

const result = await checkUrl('http://localhost:3000/pricing', {
  widths: [390, 1024, 1440],
  wait: { selector: 'main' },
  rules: ['pointer-cursor'],
});

for (const problem of result.problems) {
  console.log(problem.width, problem.check, problem.selector, problem.details);
}
if (hasProblems(result)) process.exitCode = 1;
Use it inside a Playwright test
import { test, expect } from '@playwright/test';
import { checkPage } from 'viewport-qa';

test('pricing layout holds', async ({ page }) => {
  await page.goto('/pricing');
  const result = await checkPage(page, { widths: [390, 1440] });
  expect(result.problems.filter((p) => p.severity === 'error')).toEqual([]);
});

Features

01Seven widths by default
It tests 390, 768, 1024, 1440, 1920, 2560 and 3840 pixels, or any widths you list. Widths below 768px are emulated as a phone, and the page is loaded fresh at every width.
02Overflow and clipping
Horizontal overflow, elements crossing the left or right edge, and text cut off by overflow: hidden or a fixed-height parent with no ellipsis or line clamp.
03Image resolution
Broken images, files chosen from srcset that are smaller than the rendered size times the device pixel ratio, and the same image file used more than once.
04Layout shift
Cumulative layout shift since navigation, with a default threshold of 0.1.
05Consistency checks
Edge-touching bands, panels that use more than one left and right inset or corner radius, and grids of equal items whose last row is partly filled.
06Opt-in house rules
Rules such as pointer-cursor and no-native-select are off until you name them, so they encode your design style without surprising anyone else.
07Thresholds you can change
Every number is a threshold. Override one with --threshold layoutShift=0.05, or print all of them with viewport-qa --list.

CLI usage

Usage
viewport-qa <url|file.html> [options]
-w, --widths <list>
Viewport widths, comma separated. Add a height as 1440x900. Default: 390,768,1024,1440,1920,2560,3840.
--checks <list>
Objective checks to run, or none. Default: all.
--rules <list>
Opt-in house rules to run. Default: none.
--wait <selector|ms>
Wait for a selector to be visible, or for a number of milliseconds.
--threshold <n=v>
Override a threshold, for example layoutShift=0.05. Repeatable.
--fail-on <level>
Exit 1 on error (default) or on any warning.
--screenshots <dir>
Save one PNG per width. Add --full-page to capture the whole page.
--json
Print the result as JSON.
--list
List every check, rule and threshold.

Limits

  • The checks are heuristics on numbers, not a judgment of design. Intentional choices are flagged too, such as full-bleed sections under edge-touching. Switch off the checks that do not fit.
  • One state per width. Nothing is hovered, clicked or scrolled, so open menus, modals and content revealed on scroll are not measured.
  • Only img and picture resolution is checked, not CSS background-image. SVG images are skipped.
  • Layout shift counts every shift from navigation to measurement, including input-driven ones, and does not see shifts after the measurement.
  • Shadow DOM and iframes are not entered. Colour and contrast are out of scope; use axe for contrast.
  • Chromium only, through Playwright. Only Playwright 1.63 is tested.

Frequently asked questions

How do I test a website on different screen sizes?

Run viewport-qa with a URL or a local .html file. It loads the page at 390, 768, 1024, 1440, 1920, 2560 and 3840 pixels by default and prints what overflows, clips or shifts at each width. Pass --widths to choose your own.

Is it a visual regression testing tool?

No. Visual-regression tools compare screenshots against a baseline. viewport-qa has no baseline: it measures the layout of one page at each width and reports numbers. You can save a PNG per width with --screenshots, but it does not compare them.

Can it measure cumulative layout shift?

Yes. The layout-shift check reports cumulative layout shift since navigation and warns above 0.1 by default. It counts every shift up to the measurement, including input-driven ones, so treat it as a lab number.

How do I use it for Playwright responsive testing?

Call checkPage(page, { widths }) inside a Playwright test. It resizes and reloads the page for each width, runs the checks, then restores the page. Playwright 1.40 or newer is a peer dependency.

  • Web QA

    siteprobe

    A fetch-only security headers checker and website scanner: about a hundred security, SEO and speed checks, with a score and a fix hint for each finding.

  • Web QA

    static-preflight

    A broken link checker and launch checklist for a static site build: SEO basics, links and assets, redirects, share cards, icons, JSON-LD and old-URL coverage.

See all 9 open-source packages

Author

Built by Saimul Islam

Saimul Islam is a Forward Deployed Engineer and Solutions Architect. Several of these packages run in production on DeveloperLook, the Bundlewise CRM and Sitessa.