Playwright Screenshot Scale Factor: Node.js Guide
To set the device scale factor for Playwright screenshots in Node.js, you create a browser context with the deviceScaleFactor option and then take the screenshot within that context. This option simulates a high-DPI (Retina) display, so a screenshot taken at a scale factor of 2 will be twice as wide and twice as tall in pixels as the CSS viewport size.
Why Device Scale Factor Matters
Device scale factor (DSF) is the ratio between physical pixels and CSS pixels on a screen. A standard laptop has a DSF of 1, while many phones and high-end laptops have a DSF of 2 or 3. When you take a screenshot without setting DSF, Playwright captures at 1x, which can look blurry or pixelated when viewed on a high-resolution display or when printed. By setting the DSF, you tell the browser to render the page as if it were on a device with that pixel density, producing sharper images.
How to Set Device Scale Factor in Playwright
In Playwright (v1.x and later), the deviceScaleFactor is a property of the BrowserContext options. Here’s a minimal example:
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch();
const context = await browser.newContext({
deviceScaleFactor: 2, // 2x for Retina-like output
});
const page = await context.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();
})();
If you are using Playwright’s test runner, you can set it in the test’s use block:
test.use({ deviceScaleFactor: 2 });
test('screenshot with high DPI', async ({ page }) => {
await page.goto('https://example.com');
await page.screenshot({ path: 'screenshot.png' });
});
Using Playwright’s Device Descriptors
Playwright provides a devices object with pre-defined device profiles that include the correct deviceScaleFactor for popular devices. For example, to emulate an iPhone 13:
const iPhone13 = devices['iPhone 13'];
const context = await browser.newContext({
...iPhone13,
});
This automatically sets deviceScaleFactor: 3 (and also viewport size, user agent, etc.). Using device descriptors is the easiest way to get realistic screenshots for mobile devices.
How to Choose the Right Scale Factor
The right value depends on your goal:
- 1 – Standard desktop screens, fastest and smallest file size.
- 2 – Common for high-DPI laptops (e.g., MacBook Pro) and many Android phones.
- 3 – Used by newer iPhones and some high-end Android devices.
If you’re taking screenshots for documentation or visual regression testing, a DSF of 2 is a safe middle ground. For pixel-perfect mobile previews, use the device descriptor that matches your target device.
Common Problems and Solutions
Blurry screenshots
If your screenshots look blurry, you likely forgot to set deviceScaleFactor or set it to 1. Increase it to 2 or 3.
Screenshots are too large in file size
Higher DSF produces more pixels, so file size grows. Use a DSF of 2 instead of 3 if you don’t need the extra detail, or compress the image after capture.
Layout looks different than expected
Setting a high DSF can trigger different CSS media queries (e.g., min-resolution). This is usually intended, but if you want the layout to stay the same while just increasing resolution, you can’t do that directly – DSF inherently affects rendering.
Comparison with Other Methods
Some developers try to set the viewport size to double the dimensions instead of using DSF. That approach changes the CSS viewport, which can break responsive layouts. DSF is the correct way because it keeps the CSS viewport constant while increasing the physical pixel count. For example, a viewport of 375×812 with DSF 2 produces a screenshot of 750×1624 pixels – perfect for an iPhone X.
Performance and Resource Considerations
Higher DSF means more pixels to render, which can slow down screenshot capture and increase memory usage. If you take many screenshots in a CI pipeline, consider using DSF 2 as a compromise. Also, screenshots with DSF 3 can be extremely large (e.g., 1170×2532 for iPhone 13), so make sure your storage and bandwidth can handle it.
Frequently Asked Questions
Can I set deviceScaleFactor after the context is created?
No, deviceScaleFactor is a context-level option and must be set when calling browser.newContext(). You cannot change it on an existing context. You would need to create a new context.
Does deviceScaleFactor affect the screenshot file dimensions?
Yes. If your viewport is 800×600 and you set DSF to 2, the screenshot will be 1600×1200 pixels. The CSS layout remains 800×600, but the output image has double the resolution.
What is the default deviceScaleFactor in Playwright?
The default is 1. If you don’t specify it, screenshots are captured at 1x resolution.
Can I use deviceScaleFactor with fullPage screenshots?
Yes, it works with fullPage: true. The entire page will be captured at the specified scale factor, so the image height will also be multiplied.
Does deviceScaleFactor affect the page’s CSS media queries?
Yes, it can. Browsers use the scale factor to evaluate resolution media queries. For example, a DSF of 2 may trigger styles meant for high-DPI displays.
Is there a way to get a screenshot without the scale factor but still sharp?
You could increase the viewport size, but that changes the layout. The only correct way to get high-resolution screenshots without changing the layout is to use deviceScaleFactor.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.