Use a browser automation library to launch a browser without a visible window, navigate to a page, interact with controls, verify the result, and save evidence such as a screenshot. For a new workflow that needs more than one browser engine, Playwright is a practical starting point; Puppeteer is also a good fit when its JavaScript API and Chrome-and-Firefox automation model suit your project. Neither is universally faster or more reliable: choose based on browser coverage, runtime, existing code, and the browser behavior your task must reproduce.
What a headless browser does
A headless browser is a browser controlled by code without displaying a normal browser window. It still loads pages, runs page scripts, and responds to interactions. Your automation must therefore handle the page’s changing state just as a person or a visible-browser test would: navigation can take time, elements can appear late, and overlays can block a control.
A typical job has five parts: launch a browser, create an isolated context, open a page, perform an action and check what changed, then save a result and close the browser. Headless mode is useful for repeatable jobs and unattended environments, but does not make a workflow immune to site changes, bot checks, or access restrictions.
Choose Playwright or Puppeteer
Both libraries automate pages and can produce screenshots or PDFs. Their documented browser coverage and APIs differ. Playwright documents Chromium, Firefox, and WebKit, as well as branded Chrome and Edge channels. Chrome for Developers describes Puppeteer automation for Chrome and Firefox using CDP and WebDriver BiDi. See the Playwright browser guide and Chrome for Developers’ Puppeteer overview.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
| Decision | Playwright | Puppeteer | How to choose |
|---|---|---|---|
| Browser targets | Chromium, Firefox, WebKit, and branded Chrome and Edge channels are documented. | Chrome for Developers describes Chrome and Firefox support through CDP and WebDriver BiDi. | Start from the exact engines and browser channels you need to validate; a browser engine build is not identical to every branded browser. |
| Workflow | Official docs describe locators, auto-waiting, Playwright Test, and cross-browser configuration. | Chrome’s overview highlights page interaction, screenshots, PDFs, performance analysis, and network interception. | Match the library to your language, team conventions, existing tests, and runner needs. |
| Headless behavior | Playwright documents a Chromium headless shell and a newer Chromium headless option; Chrome and Edge modes can differ. | Chrome’s overview describes headless, headful, and shell modes. | Run the same mode and browser channel you intend to deploy; do not assume all headless builds behave alike. |
Playwright is a sensible default when cross-engine validation is important. Puppeteer can be a natural fit for a JavaScript project already organized around its API. Compare the documentation for your actual target rather than choosing on an unsupported speed or reliability claim. Playwright’s browser details are at playwright.dev/docs/browsers.
Install the library and matching browser
The example below uses Playwright with Node.js. Install the package and its browser binaries; Playwright versions expect particular browser binaries, so install them again after updating the package. The official guide documents browser installation and system dependencies: Playwright: Browsers.
-
Create a project if you do not already have one:
npm init -y. -
Install Playwright:
npm install playwright. -
Install its supported browser binaries:
npx playwright install.Recommended: Fix Windows Errors and Clear Junk Files in Minutes - Free Scan →Recommended: Update Every Outdated Driver on Your PC in One Scan - Free →Recommended: PC Feels Slow? A Free Scan Shows What's Dragging Windows Down →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
On a Linux environment missing browser system packages, use the documented dependency installation, for example
npx playwright install-deps, or the combined install option documented for your environment.
Browser downloads use Microsoft’s CDN by default according to the Playwright browser guide. In restricted CI environments, confirm downloads are allowed or arrange the supported browser installation as part of the build image. Keep the Playwright package and installed browsers aligned.
Build a repeatable browser workflow
This runnable pattern opens a page, clicks a control by its accessible role and name, checks for a visible result, saves a screenshot, and closes the browser even if an action fails. Replace the example URL and button name with a page and control you are authorized to automate. The Playwright Page API documents launch, context, navigation, and screenshot workflows; the migration guide explains locator-based interactions and assertions.
const { chromium, expect } = require('@playwright/test');
(async () => {
const browser = await chromium.launch({ headless: true });
try {
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('https://example.com');
await page.getByRole('button', { name: 'Continue' }).click();
await expect(page.getByText('Welcome')).toBeVisible();
await page.screenshot({ path: 'result.png', fullPage: true });
} finally {
await browser.close();
}
})();For this exact snippet, install the test package as well as Playwright with npm install playwright @playwright/test. The imported expect helper comes from @playwright/test. Save the file as task.js and run node task.js. If you prefer not to use the test package, use an explicit condition and throw an error when the expected page state is absent.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteUse isolated state and deliberate checks
A browser context separates cookies and other session state from other contexts. Create a fresh context for jobs that should not inherit a previous run’s login or preferences. Use a persistent profile only when retaining browser state is an intentional requirement and the data is protected.
Prefer locators tied to accessible roles and names, labels, or stable attributes over brittle positional selectors. Playwright locators retry while waiting for actionability, and web-first assertions wait for expected state. A locator that matches multiple elements can fail rather than silently choosing an arbitrary one; treat that as a useful signal to make the target specific. Details are in Playwright’s migration guide.
Auto-waiting does not mean every job needs an arbitrary delay, nor does it mean explicit waits are never appropriate. Wait for a meaningful signal: a particular element, a navigation event, a download, or an application state. Fixed sleeps are fragile because a fast page wastes time and a slow page can outlast the guessed delay.
Handle special interactions explicitly
- Downloads: coordinate the download event with the action that starts it, then save or inspect the resulting file.
- Uploads: use the file chooser flow or set files on the relevant input; Playwright documents
setFilesfor this case. - Dialogs: register a handler for expected alerts, confirms, or prompts before triggering the action that opens one.
- Overlays: deal with predictable modals as part of the workflow. Playwright locator handlers can address unexpected overlays, but the handler may alter focus and mouse position, so make the next interaction self-contained.
Consult the Playwright Page API for screenshots, PDFs, file chooser interactions, and overlay handler behavior.
Capture useful evidence
Use assertions to make success observable, then save the artifact that helps a person or another system inspect the outcome. Screenshots are useful for visual output and failures; PDFs suit document capture. For long-running jobs, structured logs and retaining failure artifacts make diagnosis easier. Puppeteer’s documented use cases also include screenshots, PDFs, UI testing, and performance analysis; these capabilities do not imply a performance advantage over Playwright.
Run the same workflow in CI or production
- Pin and record the automation package version and the browser channel or binary used by the job.
- Install the browser binaries and required system dependencies in the environment that runs the task, not just on a developer laptop.
- Choose headless or headful mode intentionally and test that exact mode. Playwright distinguishes its Chromium headless shell from a newer headless mode; branded Chrome and Edge may behave differently.
- Keep outputs, logs, and error details for failed runs. Do not expose authentication cookies, access tokens, or private page content in logs or artifacts.
- Use reasonable timeouts and explicit success checks so that a navigation finishing is not mistaken for the application being ready.
- Check that automation of the target is permitted and respects its terms and access controls. A headless browser is not a method for bypassing bot defenses.
Chrome for Developers quotes its documentation about the newer mode: “New Headless on the other hand is the real Chrome browser, and is thus more authentic, reliable, and offers more features.” This statement refers to newer Chrome headless, not every headless implementation. Read the mode description in the Playwright browser guide before treating it as applicable to a particular binary.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common failures
| Symptom | Likely cause | What to do |
|---|---|---|
| Browser executable is missing or will not launch | The package’s matching browser binaries or system dependencies are absent. | Run npx playwright install; on Linux, install documented system dependencies with npx playwright install-deps. Check whether the build environment permits browser downloads. |
| Works locally but not in CI | Different browser revisions, dependencies, headless modes, or browser channels. | Record package and browser versions, install browsers in CI, and reproduce with the same mode and channel used in deployment. |
| Click times out or hits the wrong control | The locator is ambiguous, the element is not actionable, or an overlay intercepts the interaction. | Use a more specific role/name or stable attribute, assert the expected state, and handle a known overlay deliberately. |
| Script runs ahead of a dynamic page | The workflow assumes navigation completion means the application is ready. | Wait for the relevant locator or app state and assert it instead of adding a guessed fixed sleep. |
| Screenshot differs from a visible browser | Headless shell, newer headless, Chrome, and Edge are not interchangeable modes or builds. | Capture with the precise channel and mode that matters to the task; use screenshots to inspect the difference. |
| Unexpected dialog, file prompt, or modal interrupts the run | The workflow has not registered the appropriate handler or file interaction. | Set up the dialog, file chooser, or overlay behavior before the action that triggers it, then verify the resulting page state. |
Or skip the browser setup
If the task is to capture a website rather than interact with its controls, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. For example, save a clean WebP capture with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for parameters. Cookie banners are accepted and removed before capture; known consent platforms, newsletter popups, and chat widgets can be removed, with each step configurable. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteThe free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo free.
Frequently asked questions
Can I automate every website with a headless browser?
No. A site may require authentication, restrict automated access, or use bot checks. Confirm permission and access requirements for the specific site; neither library guarantees access.
Should I always use headless mode?
No. Use headless for unattended execution when it matches the task. During diagnosis, a visible browser can make interaction and rendering problems easier to inspect. Validate the same mode and browser channel you will rely on.
Does page navigation finishing mean the task is complete?
No. The application may still be rendering or waiting for data. Check the specific visible state that indicates your task succeeded.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
