How to Test a Locally Hosted Website for Responsive Design

To test a locally hosted website for responsive design, open it in a browser’s responsive device mode, resize the viewport from narrow to wide, and inspect the layout at and around the breakpoints defined by the site. Check more than appearance: look for clipped content, unintended horizontal scrolling, reachable navigation and controls, and interactions that still work. For repeatable checks, run the page at explicit viewport sizes with Playwright, then validate important touch or platform-specific behavior on actual target devices.

Responsive testing is about how a layout behaves across a range of viewport widths, especially where its CSS media queries change the layout. Checking only a few device presets can miss problems at intermediate widths or near a breakpoint.

1. Start your local site

Start the development server using the command documented by your project, then open the local URL it prints or documents. Commands and ports vary by framework and project, so use the project’s instructions rather than assuming a universal command or address.

Keep the server running while you test. If the page does not load in the browser, confirm that the server started successfully and that you opened the URL it reports. Resolve that first; responsive tools cannot inspect a page that is unavailable.

2. Check the page in browser device mode

Chrome DevTools Device Mode and Microsoft Edge’s device emulation provide a responsive viewport that you can resize. Open DevTools, enable device emulation, and use the responsive sizing controls to inspect the local page at different widths. The exact UI labels may change between browser versions.

Begin at a narrow width that represents the smallest layout you support.
Widen the viewport gradually through intermediate sizes, watching for awkward wrapping, cramped controls, and sudden layout shifts.
Check the widest layout you support.
When you find a breakpoint, inspect just below and just above it. A layout can work at the preset widths and still fail during the transition.
Repeat on pages with different structures, such as a long article, a data table, a form, or a page with a complex navigation menu.

Use the page’s own media queries to identify relevant breakpoints. In Edge, the documented device emulation tools can display breakpoint indicators for width conditions; the underlying principle is that media queries respond to viewport width.

3. Use a responsive design checklist

At every size you check, inspect the content and try the main interactions. This checklist is a practical starting point, not a universal certification that a site is responsive.

Content: Is text readable and visible? Are headings, images, and embedded content inside the page rather than clipped?
Overflow: Does the page avoid unintended horizontal scrolling? If a specific component, such as a wide table, needs horizontal scrolling, is that behavior contained and usable?
Navigation: Can visitors reach the main sections? If navigation changes to a menu, does it open, close, and allow links to be selected?
Controls: Can you use buttons, form fields, links, and dialogs at narrow sizes? Do controls overlap or become hard to reach?
Layout transitions: Do columns, sidebars, and spacing change at sensible widths? Does anything jump, disappear, or overlap near a breakpoint?
Images and media: Do images fit their containers? Can videos and other embedded elements be viewed without pushing the page wider?
Real interactions: Try menus, forms, tabs, and other important controls instead of judging only a static view.

Check the initial viewport and content farther down the page. A header may adapt correctly while a lower section, table, or embedded widget causes overflow.

4. Make viewport checks repeatable with Playwright

For regression checks, automate a small set of representative viewport sizes. Playwright supports configuring viewport and device characteristics, including screen size, user agent, and touch. It supports Chromium, WebKit, and Firefox, so a project can exercise more than one browser engine.

The following example assumes a Playwright project has been set up and that its local server is already running. Replace the URL and widths with values appropriate to your project. It checks that the page loads and reports the document and viewport widths; a width mismatch can flag horizontal overflow for investigation, though some pages intentionally contain scrollable components.

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

const viewports = [
  { name: 'narrow', width: 375, height: 812 },
  { name: 'intermediate', width: 768, height: 1024 },
  { name: 'wide', width: 1440, height: 900 },
];

for (const viewport of viewports) {
  test(`responsive layout at ${viewport.name} width`, async ({ page }) => {
    await page.setViewportSize({
      width: viewport.width,
      height: viewport.height,
    });
    await page.goto('http://localhost:3000', { waitUntil: 'domcontentloaded' });

    await expect(page.locator('body')).toBeVisible();
    const dimensions = await page.evaluate(() => ({
      viewportWidth: document.documentElement.clientWidth,
      documentWidth: document.documentElement.scrollWidth,
    }));

    expect(
      dimensions.documentWidth,
      `Unexpected page overflow at ${viewport.width}px: ${JSON.stringify(dimensions)}`
    ).toBeLessThanOrEqual(dimensions.viewportWidth);
  });
}

Set the URL to the local address for your app. If your page intentionally has a full-width element or contained horizontal scroller, refine the assertion to check the page shell or the specific element that should fit. A raw document-width check identifies a symptom; it does not explain which element caused it.

For device-specific behavior, use Playwright’s device emulation configuration as appropriate to the project, and include the browser projects you want to cover. Viewport resizing alone does not simulate every property of a physical device. Use Playwright’s emulation documentation for configurable device characteristics and its browser documentation for engine support.

5. Add a local Lighthouse audit when useful

Lighthouse can complement visual and interaction checks with a local audit in Chrome. Its configuration defaults to mobile emulation and also provides a desktop preset. Use it to find audit issues, not as proof that every responsive layout and interaction is correct: a score cannot replace checking the page at your own breakpoints and trying its controls.

See the Lighthouse project’s emulation documentation and README for current configuration and local auditing details.

6. Know what emulation can and cannot tell you

Browser emulation is useful for quickly inspecting selected viewport and device conditions. It is still a simulation. If touch behavior, platform-specific rendering, or a particular device is important to the product, check the page on representative physical hardware as well. Prioritize devices and browsers that match your users and the behavior you need to validate.

Choose a testing method

Method	Best for	Coverage and limits
Browser responsive mode	Fast exploratory checks during development	Easy to resize and inspect interactively; coverage depends on the sizes and browsers you check.
Playwright	Repeatable checks in a regression workflow	Can configure viewport and device characteristics and run supported browser engines; checks only the scenarios you implement.
Lighthouse	A complementary local audit	Provides mobile and desktop emulation configurations; its audit score does not establish that all layouts or interactions work.
Physical devices	Important touch and platform-specific validation	Shows behavior on the hardware tested; it does not cover every possible device.

Performance, reliability, and cost

Manual responsive checks need little setup and provide immediate visual feedback, but they are easy to perform inconsistently. Scripted checks take initial configuration and maintenance, then can rerun the same selected cases as the site changes. Keep automated scenarios focused on supported widths, important breakpoints, and high-value interactions; use interactive inspection to explore unexpected layout problems. Lighthouse is an additional audit path, not a substitute for those checks.

These methods use browser tools and software; the workflow does not require a specific physical product. Real-device validation does require access to the representative hardware you intend to check. The research sources do not establish universal timing or cost figures, so actual setup and run costs depend on the project and environment.

Common problems and fixes

Symptom	Likely cause	What to do
The local page does not open	The development server is stopped, failed to start, or the browser URL does not match the project’s local address.	Check the server output and project instructions, then open the address the server provides.
The page looks fine at presets but breaks between them	Only named device sizes were checked; a layout transition or media-query breakpoint falls in between.	Resize gradually and test just below and above the page’s breakpoints.
A horizontal scrollbar appears	An element is wider than the viewport, or the page intentionally contains a horizontally scrollable component.	Inspect the overflowing element. Fix unintended width or wrapping issues; keep intentional scrolling contained to its component.
A Playwright overflow assertion fails	The document is wider than the viewport, or a legitimate component scrolls horizontally.	Inspect the rendered page at the failing width and narrow the assertion to the page shell or elements that must fit.
An automated page check fails to load the app	The local server is unavailable at the URL used by the test, or the test runs before the server is ready.	Start the app as documented and confirm the configured URL is reachable before running the test.
Emulation passes but a real device behaves differently	Emulation approximates selected characteristics and does not establish behavior on every physical device.	Reproduce on representative hardware, especially when touch or platform-specific behavior matters.

Or skip the browser setup

If you also need screenshots of pages, ScreenshotNeo is a website screenshot API and MCP server. A screenshot can help you compare how a page renders at a chosen viewport, but it does not replace testing interactions or checking on physical devices. The API accepts viewport and device options; see the ScreenshotNeo API documentation for configuration and the other supported parameters.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before the shot; newsletter popups and chat widgets are removed too. Each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report the page verdict and billing status.
An MCP server lets AI agents, including Claude, Cursor, and other MCP clients, take screenshots.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

FAQ

Should I test only common phone and desktop sizes?

No. Include intermediate widths and inspect just above and below the breakpoints your page uses; transitions are a common place for layout problems to appear.

Does a passing screenshot prove the site is responsive?

No. A screenshot shows a rendered state. You still need to inspect content and overflow and exercise important controls, and use physical devices when device-specific behavior matters.

Do I need Playwright to test responsive design?

No. Browser responsive mode is enough for interactive spot checks. Playwright is useful when you want the same selected viewport checks to run repeatedly.