How to Take a Mobile Webpage Screenshot with Playwright

Use a Playwright device preset to emulate a mobile browser, open the page, and call page.screenshot(). The default screenshot captures the visible viewport; set fullPage: true to capture the full scrollable page. This is browser emulation, not a screenshot from a physical phone.

1. Set up a mobile device project

Install Playwright Test if it is not already in your project:

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

Add a mobile project to playwright.config.ts. A device preset supplies device-related browser settings such as viewport, user agent, screen size, and touch support. See the Playwright emulation guide for the device registry and configuration details.

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

export default defineConfig({
  projects: [
    {
      name: 'Mobile Safari',
      use: {
        ...devices['iPhone 13'],
      },
    },
  ],
});

Create a test, for example at tests/mobile-screenshot.spec.ts:

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

test('capture a mobile webpage', async ({ page }) => {
  await page.goto('https://example.com');
  await page.screenshot({ path: 'mobile.png' });
});

Run only that project with npx playwright test --project="Mobile Safari". The screenshot is written to the path given in the test. Playwright’s Page API documents screenshot options.

2. Choose viewport or full-page capture

A regular screenshot captures the page area currently visible in the emulated viewport. To include content below the fold, use fullPage: true:

await page.screenshot({ path: 'mobile-viewport.png' });
await page.screenshot({ path: 'mobile-full.png', fullPage: true });

Full-page capture can produce a tall image and may expose layout issues that are not visible in a single screen. Use viewport capture for a specific mobile screen state and full-page capture when you need the whole scrollable document.

3. Wait for the page state you need

Navigate to the target URL, then wait for the relevant content to be ready before taking the screenshot. There is no universally correct fixed delay: pages differ, and a fixed wait can be either too short or unnecessarily slow. Prefer waiting for a selector that identifies the content in your page.

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

test('capture after the main content appears', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page.locator('main')).toBeVisible();
  await page.screenshot({ path: 'mobile-ready.png', fullPage: true });
});

If a page requires a known interaction before the desired state appears, perform that interaction before the screenshot. The image records the page state at capture time.

4. Configure mobile behavior manually when needed

If a preset does not fit your target, configure mobile dimensions and behavior explicitly. For example:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    viewport: { width: 390, height: 844 },
    isMobile: true,
    hasTouch: true,
  },
});

Reducing the viewport alone is not equivalent to mobile device emulation. The isMobile option affects how the browser handles the meta viewport and touch behavior; hasTouch enables touch support. Playwright documents that isMobile is not supported in Firefox. Consult the BrowserType API for the option’s behavior and browser support.

When extending a preset, be careful about later overrides. Configuration order matters: an explicit viewport set after spreading a device preset can replace its viewport dimensions. Keep preset values intact unless you mean to change them.

5. Choose image format and pixel scale

The screenshot path extension can select PNG, JPEG, or WebP output. For example, use mobile.webp for WebP or mobile.jpg for JPEG. Choose the format according to the downstream tool or review workflow.

The screenshot API’s scale option controls the relationship between CSS pixels and image pixels. scale: 'css' produces one image pixel per CSS pixel. Device scale uses device pixels and can produce a larger image. Use CSS scale when a compact image at CSS dimensions is useful; use device scale when the higher pixel density is part of the evidence you need.

await page.screenshot({
  path: 'mobile-css-scale.png',
  scale: 'css',
});

For the complete set of screenshot arguments and format details, see the Page.screenshot API documentation.

6. Emulation versus a real Android device

For responsive layout work, Playwright’s device emulation is generally the direct path and does not require a physical phone. It simulates browser device settings; it does not make the run equivalent to validating on every real device.

If you specifically need automation against an attached Android device or Android Virtual Device (AVD), Playwright documents a separate Android workflow that requires a device or AVD and a running, authenticated ADB daemon. See the Playwright Android guide. This is an optional, distinct workflow, not a prerequisite for emulated mobile screenshots.

7. Keep visual comparisons repeatable

If screenshots are used as visual baselines, keep the browser and execution environment consistent with the environment that created the baseline. Playwright notes that rendering can vary with operating system, browser version, settings, hardware, power source, and headless mode. See Playwright visual comparisons.

When a visual result changes unexpectedly, first check whether the browser version or execution environment changed. Also make sure the page reached the same state and that the viewport and scale settings match.

8. Troubleshooting

Symptom	Likely cause	Fix
The screenshot is desktop-shaped or uses the wrong dimensions	The mobile project was not selected, or a later viewport setting overrode the preset.	Run with `--project="Mobile Safari"`, inspect the project’s `use` configuration, and check the order of preset spreads and explicit overrides.
The page looks squeezed instead of using a mobile layout	Only the viewport width was reduced, without the relevant mobile behavior.	Use a device preset or configure supported mobile options such as `isMobile` and `hasTouch`. Check the target browser’s support.
Content is missing from the screenshot	The screenshot was taken before that content appeared, or the default viewport capture excludes content below the fold.	Wait for a locator representing the needed content. Use `fullPage: true` when content below the viewport should be included.
The image is unexpectedly large	Device-pixel scale or a full-page capture produces more image pixels than expected.	Try `scale: 'css'` for CSS-pixel output, or capture only the viewport if the full document is not needed.
`isMobile` does not work in Firefox	Playwright does not support `isMobile` in Firefox.	Use a supported browser and confirm its device configuration in Playwright’s browser documentation.
Visual snapshot comparisons differ between runs	Browser or environment differences can change rendering.	Keep the browser version, operating system, settings, hardware, and headless mode consistent where possible; ensure the page reaches the same state.
Android automation cannot find or control a device	The separate Android workflow needs an Android device or AVD and an authenticated, running ADB daemon.	Check the ADB/device setup described in the Playwright Android guide. Use standard emulation instead if physical-device validation is not required.

9. Performance, reliability, and cost

For a single screenshot, the main work is launching or using the browser, loading the page, waiting for the required state, and rendering the image. Full-page images and device-pixel output can be larger than viewport captures at CSS scale. Capture only what the task needs, and wait on a meaningful page condition instead of applying an arbitrary long delay.

Reliable screenshot automation depends on repeatable inputs: the same target URL and page state, matching viewport and device settings, and a stable browser environment. Playwright itself is browser automation software; the supplied documentation does not specify a usage price for this workflow. Runtime and infrastructure costs depend on where you run the browser.

10. Or skip the browser setup

If you need an image from a URL without maintaining a Playwright browser workflow, ScreenshotNeo is a website screenshot API and MCP server. It returns PNG, JPEG, WebP, or PDF from one GET request. The API accepts screenshot parameters used by other screenshot APIs, which can make switching easier. See the ScreenshotNeo API documentation.

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

import requests

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

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo can capture full pages or a selected element, emulate device presets or custom viewports, and set options such as dark mode, custom CSS, waits, and image format. It accepts cookie and browser settings too. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture by default, and those cleanup steps can be turned off. Bot checks, blank pages, and failed loads are not billed; response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.

The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan. Sign up for 1,000 free screenshots a month, with no card.

FAQ

Do I need an iPhone to capture an iPhone-sized screenshot?

No. Use Playwright’s device emulation preset for a mobile browser configuration. A physical device is a separate validation option.

Does `fullPage: true` change the emulated device?

No. It changes the capture area to include the full scrollable page; device emulation comes from the project configuration.

Should I use CSS scale or device scale?

Use CSS scale for one image pixel per CSS pixel. Device scale captures at device pixel density and can result in a larger image.