Puppeteer AddScreenParams: Add a Virtual Screen
Learn what Puppeteer’s AddScreenParams refers to, why virtual screens matter for multi-display tests, and how to verify API support before relying on it.
Short answer: a virtual screen is an emulated display used to test multi-screen behavior, such as where a browser window is placed. The available research associates this capability with the Chrome DevTools Protocol (CDP) command Emulation.addScreen, but does not verify the exact Puppeteer AddScreenParams fields, availability, or compatibility requirements. Check the documentation and protocol version for the Puppeteer and Chrome versions you actually run before writing code against it.
1. What AddScreenParams is for
AddScreenParams is the title of a Puppeteer-related parameter type for adding a virtual screen. The practical goal is to give automated browser tests a multi-display environment so they can exercise behavior such as window placement. W3C meeting minutes discuss virtual displays as test-framework infrastructure for automated screen-placement tests; they do not define Puppeteer’s API contract.
A virtual display in this context is software-emulated test infrastructure. It is not the same as attaching a physical monitor, and it does not establish that a normal website can control or inspect a user’s screens. The research found a secondary result associating CDP Emulation.addScreen with this use case, but the page could not be opened and the official Puppeteer reference for the exact type was not found.
2. Verify the API before implementing it
- Record the Puppeteer package version and the browser or Chrome version used by your test runner.
- Open the version-matched Puppeteer API reference and search for
AddScreenParamsand the method that consumes it. - Check the matching Chrome DevTools Protocol documentation for
Emulation.addScreen, including any required session setup and return behavior. - Confirm the API exists in your installed version and run a minimal test in the same operating system and CI image used by your suite.
- Only then add the verified fields and lifecycle handling to your test. Keep the test isolated so unsupported environments fail clearly.
The research does not confirm property names, required values, validation limits, return type, removal behavior, exceptions, release availability, or operating-system support. A secondary result mentions dimensions, scale factor, orientation, origin, and work area as configuration concerns; treat these only as topics to verify in the authoritative, version-matched reference, not as a confirmed type schema.
3. What to test with a virtual display
- Window placement: whether the application opens or moves a window to the intended display.
- Display-dependent layout: whether the application responds as expected when the available display arrangement changes.
- Repeatability: whether the same scenario produces the expected result in local runs and CI.
- Fallback behavior: what the application does when the virtual-screen API is unavailable or the test environment cannot create the requested setup.
Keep assertions focused on behavior your application owns. The available sources do not establish a universal support matrix, so do not assume a virtual-display test will behave identically across operating systems, browsers, or headless configurations.
4. Runnable verification without guessing the API
Because the exact Puppeteer method signature and parameter fields could not be verified from the available sources, a code sample that calls the API would risk being incorrect. This Node.js script is runnable and verifies the installed package version and whether the named type or API text appears in the installed Puppeteer files. It is a discovery aid, not proof that a matching browser protocol implementation is available at runtime.
import puppeteer from 'puppeteer';
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const packageJson = require('puppeteer/package.json');
console.log(`Puppeteer package version: ${packageJson.version}`);
console.log(`Executable path: ${puppeteer.executablePath()}`);
// Then inspect the version-matched API reference and CDP protocol docs.
// Do not infer a callable method or parameter schema from a name match.Run it in a project that has Puppeteer installed with npm install puppeteer, then execute it with node verify-puppeteer.mjs. For browser-side verification, use Puppeteer’s documented CDP session APIs for your installed version to inspect the protocol, and consult the matching protocol reference before sending any command. No exact AddScreenParams payload is included here because its schema was not confirmed.
5. Choosing a test environment
| Approach | Useful when | Things to verify |
|---|---|---|
| Software-created virtual display | You need repeatable automated coverage of multi-screen behavior. | Browser and OS support, API availability, lifecycle cleanup, and CI behavior. |
| Real attached display | The scenario depends on actual hardware behavior that software emulation does not cover. | Test host configuration, display arrangement, and repeatability. |
The sources do not establish that either approach is universally better. Select based on what the test must prove, then document the environment so failures can be reproduced.
6. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| The type or method is missing | The installed Puppeteer version does not expose the API, or the reference is for a different version. | Match the package and browser versions to their documentation. Do not substitute guessed method names or fields. |
| The protocol rejects a command or parameter | The command or payload differs from the protocol version supported by the running browser. | Check the browser’s matching CDP reference and confirm every field against it. |
| It works locally but fails in CI | The browser, operating system, launch mode, or test image differs. | Log package and browser versions, align the CI image, and verify support in that environment. |
| Results vary between runs | Test setup or display state may not be isolated, or the environment may not support the same behavior consistently. | Use a fresh browser context or process as appropriate, make setup explicit, and clean up through the documented lifecycle API. |
| A page cannot see the virtual screen | The test may be confusing browser automation infrastructure with web-platform APIs available to page scripts. | Assert through the supported automation or application behavior. Do not assume a website receives access to automation-only display configuration. |
7. Performance, reliability, and cost
The research provides no benchmark or quantified performance impact for Emulation.addScreen. Treat setup as part of the test environment and measure its effect in your own suite. Reuse stable setup only when the documented API and lifecycle allow it; isolate tests if shared display state can cause interference.
For reliability, pin and report the Puppeteer and browser versions, exercise the same configuration in CI, and make unsupported environments produce an actionable skip or failure. No physical monitor or adapter is established as necessary for this API-driven task. A real display may still be required when the requirement specifically concerns hardware behavior.
8. Capture a page without managing a browser
If the task is to obtain a screenshot rather than test multi-screen window placement, ScreenshotNeo is a website screenshot API and MCP server. Its API returns an image or PDF from one GET request. See the ScreenshotNeo API documentation for configuration details.
Or skip the browser setup
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with response headers identifying the page verdict and billing status. Its MCP server provides screenshot, page-info, and PDF tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Sign up free for 1,000 screenshots a month, with no card.
9. FAQ
Does AddScreenParams let a website add a monitor?
The evidence concerns browser automation and test infrastructure. It does not establish a web-page API for adding a physical display.
Is a physical monitor required?
No requirement for physical hardware is established for the API-driven virtual-screen use case. Use real hardware when the behavior under test depends on real display hardware.
Can I copy a known AddScreenParams object into my test?
Not based on the available research. Verify the type and accepted fields against the reference matching your installed Puppeteer and browser versions.
Sources
- W3C Second Screen WG/CG TPAC 2022 meeting minutes, for discussion of virtual displays in automated testing.
- Puppeteer documentation, which should be consulted in the version-matched form to verify the exact API contract.
