The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Headless website testing runs a real browser engine without opening a visible window. The browser still parses HTML, executes JavaScript, applies CSS, makes network requests, and interacts with the page; only the graphical window is omitted. That makes it suitable for Linux servers, containers, and CI runners. Playwright launches headless by default, and Chrome documents --headless for display-free execution in servers and pipelines.
This guide shows how to build a reliable Playwright workflow, compares Playwright with Selenium, Puppeteer, and Cypress, explains browser and CI management, and gives a practical method for diagnosing flaky tests.
What headless testing actually does
A headless test drives a browser process rather than sending an HTTP request and inspecting raw HTML. It can verify client-side routing, rendered text, form behavior, cookies, local storage, responsive layouts, downloads, and other behavior that appears only after JavaScript runs.
Headless and headed are execution modes, not different test types. Run headed while developing when you need to watch the page, then run the same test headlessly in CI. A request-only check is faster for API or status-code monitoring, but it cannot validate the browser’s rendered result.
#1 Best Overall
When headless is a good fit
- Pull-request checks that must run on a server without a desktop session.
- Regression suites for single-page applications and authenticated workflows.
- Cross-browser checks in Chromium, Firefox, and WebKit.
- Scheduled smoke tests in containers or Linux runners.
When to add headed runs
Use a headed run to inspect focus, native dialogs, browser-specific rendering, or a failure that is difficult to understand from artifacts alone. Do not make a headed desktop dependency part of your normal CI path unless the test specifically requires it.
Choose a headless automation framework
The best choice depends on browser coverage, language, execution architecture, and how much control you need over contexts, network traffic, and diagnostics.
| Framework | Browser and protocol scope | Language or test model | Where it fits |
|---|---|---|---|
| Playwright | Chromium, Firefox, WebKit, plus installed Chrome and Edge channels | JavaScript/TypeScript, Python, Java, and .NET; headless by default | Cross-browser end-to-end tests, trace-based debugging, parallel CI, and controlled browser contexts |
| Selenium WebDriver | WebDriver APIs for desktop and mobile browser automation | Multiple language bindings and remote-driver architecture | Teams standardised on WebDriver, broad grid integrations, or existing Selenium suites |
| Puppeteer | Chrome and Firefox through the Chrome DevTools Protocol and WebDriver BiDi | JavaScript library with a high-level API | Chrome-focused automation, browser scripting, and Node.js tooling |
| Cypress | End-to-end and component testing | Test code runs in the same run loop as the application | Front-end teams that value an in-browser test experience and component testing |
There is no universal winner. Playwright is a practical default when one suite must cover several browser engines and produce rich CI evidence. Selenium remains sensible when WebDriver compatibility or an existing remote grid is the deciding factor. Puppeteer is concise for Chrome-oriented scripts. Cypress’s in-application run loop is a different architecture from Selenium’s network-based remote commands, so migration requires more than changing method names.
Build a Playwright test that runs headlessly
Install a pinned project
- Create a Node.js project and install Playwright as a development dependency:
npm install --save-dev @playwright/test. - Install the browser binaries and Linux dependencies expected by your Playwright version:
npx playwright install --with-deps. - Keep the package-lock file in version control so local and CI installs resolve the same framework version.
Playwright expects browser binaries associated with its own version. Installing a different global browser does not replace that requirement.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC 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 & 11Example test
import { test, expect } from '@playwright/test';
test('home page has a working navigation link', async ({ page }) => {
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await expect(page).toHaveTitle(/Example Domain/);
await expect(page.locator('h1')).toHaveText('Example Domain');
});Run it headlessly with npx playwright test. For local investigation, use npx playwright test --headed; the assertions and browser context remain the same.
Use stable synchronization
- Prefer role, label, and test-id locators over long CSS or XPath paths tied to layout.
- Use Playwright’s web-first assertions, which wait for the expected state, instead of arbitrary sleeps.
- Wait for a meaningful UI condition such as a visible result, enabled button, or completed navigation.
- Use a fixed delay only for a documented external constraint; delays hide race conditions and lengthen every run.
Put the tests in CI
Minimal GitHub Actions workflow
name: browser-tests
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
- if: always()
uses: actions/upload-artifact@v4
with:
name: playwright-report
path: playwright-report/The documented sequence is package installation, browser and operating-system dependency installation, test execution, and publication of the HTML report or other artifacts. Keep the if: always() condition so a failed test does not erase the evidence needed to diagnose it.
Control workers and parallel jobs
Start with one worker in CI for deterministic resource use. Once the suite is isolated and the runner has capacity, increase workers or shard the suite across jobs. Parallel tests must not share mutable accounts, files, ports, or database records unless those resources are deliberately isolated.
Sharding reduces wall-clock time by distributing test files across independent jobs. It also increases setup overhead and can make external service limits the new bottleneck, so measure the whole workflow rather than multiplying worker counts blindly.
Free tools Windows power users keep installed
One-click scans. No signup required.
Cache with care
Playwright notes that restoring a browser cache can cost as much as downloading the binaries, particularly when Linux dependencies still have to be installed. Cache package-manager data when it helps, but compare restore time, cache size, and invalidation frequency with a clean install. Always invalidate browser caches when the Playwright version changes.
Manage browser binaries and runtime fidelity
Install only what the job needs
npx playwright installinstalls the browsers.npx playwright install-depsinstalls operating-system dependencies.npx playwright install --with-depsperforms both operations.npx playwright install --only-shellinstalls the Chromium headless shell for headless-only jobs and can reduce the downloaded payload.
Choose a browser channel deliberately
Playwright-managed Chromium gives reproducible binaries. Branded Chrome or Edge channels test the browser already installed on the machine, which can improve fidelity to a managed desktop fleet but makes the runner image part of your dependency set. Record the chosen channel in CI configuration and update it intentionally.
Headless-shell execution and a full browser channel are not interchangeable in every edge case. If a failure appears only in one mode, reproduce it with the same binary and launch settings used by CI before changing application code.
Make tests reliable instead of merely headless
Isolate state
Create a fresh browser context for each test or fixture boundary that requires isolation. Use independent test data, unique filenames, and separate accounts for concurrent tests. Clear or explicitly seed cookies, local storage, and permissions rather than relying on the order in which tests happen to run.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Control external dependencies
Decide which third-party calls should be real. For deterministic regression tests, route unstable services to a controlled response and reserve a smaller set of tests for real integrations. Record the contract being tested so a mocked response does not conceal a broken integration.
Set meaningful timeouts
Use a normal test timeout, a shorter assertion timeout, and a separately justified timeout for known slow operations. Increasing every timeout when one request is slow turns a transient problem into a long queue and can exhaust CI capacity.
Keep test data and clocks predictable
Seed data through an API or fixture rather than clicking through an administration UI in every test. Fix time zones and locale where date formatting matters. Use stable, non-production credentials and revoke them when a job ends.
Capture evidence before rerunning a failure
Trace viewer
Enable traces for failures or for the first retry. Playwright’s trace viewer presents a timeline with DOM snapshots, network requests, console information, and screenshots. That lets you inspect the failed state without immediately reproducing a race.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsReports and low-level logs
- Publish the HTML report, screenshots, and video according to your retention policy.
- Capture console messages and relevant network failures in test fixtures.
- Set
DEBUG=pw:browserwhen diagnosing browser-launch failures. - Include the browser channel, Playwright version, operating-system image, worker count, and shard number in CI metadata.
Evidence should identify whether the problem is application behavior, test synchronization, browser startup, a network dependency, or runner capacity. A rerun that passes without artifacts is not a diagnosis.
Common headless failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Browser executable is missing | The framework package was installed but its matching browser was not | Run npx playwright install --with-deps in the same image and verify the Playwright version. |
| Launch fails with shared-library or sandbox errors | Missing Linux dependencies or an unsuitable container policy | Install dependencies with Playwright’s command, use a supported container image, and inspect DEBUG=pw:browser output before changing launch flags. |
| Test passes headed but fails headlessly | Timing race, viewport difference, animation, or browser-channel difference | Replace sleeps with state-based assertions, set an explicit viewport, disable nonessential animation, and reproduce with the CI browser binary. |
| Element is present but not clickable | Overlay, animation, detached node, or incorrect locator | Assert visibility and enabled state, target a semantic locator, and capture a trace to identify the overlay. |
| Only one shard fails | Shared state, order dependence, or insufficient runner resources | Run the file alone, randomize order locally, isolate data and ports, and compare CPU, memory, and network pressure between shards. |
| Tests time out on navigation | Slow or blocked third-party request, redirect loop, or service outage | Capture network information, set an explicit navigation condition, mock nonessential dependencies, and investigate the service separately. |
| Cache restores but the job is still slow | Operating-system dependencies still require installation | Measure cache restore versus a clean download and invalidate stale browser caches after framework upgrades. |
Performance, parallelism, and cost decisions
- Reduce work first: reuse authenticated setup where safe, avoid repeating expensive seed operations, and test the smallest page state that proves the behavior.
- Then add concurrency: workers and sharding shorten elapsed time only when the CI machine, database, and external services have spare capacity.
- Keep retries bounded: a single diagnostic retry can preserve evidence; unlimited retries hide regressions and increase queue time.
- Track artifact volume: screenshots, videos, and traces are valuable for failures but expensive to retain for every passing test.
- Pin versions: changing the framework, browser binary, and runner image simultaneously makes failures difficult to attribute.
Or skip the browser setup
If your goal is a clean visual capture rather than a behavioral assertion, ScreenshotNeo provides a website screenshot API and MCP server. It accepts a URL and returns PNG, JPEG, WebP, or PDF without you maintaining a browser image.
One request is enough:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpEquivalent Python:
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)Equivalent Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
const buffer = Buffer.from(await res.arrayBuffer());
await Bun.write('shot.webp', buffer);See the parameter reference and response details in the ScreenshotNeo documentation. Before capture, it can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether the request was billed.
Options for production captures
- Full-page capture loads lazy images; you can capture one element by CSS selector, hide selectors, click an element first, or inject custom CSS and JavaScript.
- Select dark mode, any viewport, 12 device presets, and retina scale.
- Render PDF with paper size, margins, landscape orientation, and page ranges.
- Convert supplied HTML and CSS to an image, use transparent backgrounds, or resize the output.
- Wait for a selector, a delay, or network idle; block ads, trackers, requests, or resource types.
- Supply custom headers, cookies, user agents, Authorization, time zone, and geolocation.
- Choose a cache TTL, create signed links for public
<img>tags, submit asynchronous jobs with signed webhooks, or capture up to 100 URLs in one bulk call. - Use the usage API and OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify migration.
AI-agent access and pricing
The MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. Every feature is available on every plan.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Plan | Allowance | Price |
|---|---|---|
| Free | 1,000 shots per month | $0, no card |
| Starter | 3,000 shots | $5 |
| Growth | 15,000 shots | $15 |
| Pro | 60,000 shots | $39 |
| Scale | 250,000 shots | $99 |
| Business | 1,000,000 shots | $249 |
Yearly billing provides two months free. Start with 1,000 free screenshots a month with no card, then choose a paid plan starting at $5 for 3,000 shots if your volume requires it.
FAQ
Does headless mean the site is not rendered?
No. A headless browser still renders and executes the page; it simply does not display a desktop window. Rendering, JavaScript behavior, and network activity can be tested normally.
Should every CI test run in parallel?
No. Begin with one worker, prove that tests isolate their state, and add workers or shards only when the runner and dependent services can sustain them.
Is a screenshot API a replacement for browser tests?
No. A screenshot API is useful for visual captures and documents, while Playwright, Selenium, Puppeteer, or Cypress verify interactions and assertions. Use each for the job it is designed to perform.
When should I use a branded Chrome or Edge channel?
Use one when matching an installed, managed browser is more important than Playwright-managed binary reproducibility. Keep the channel and runner image pinned so a silent browser update does not change test behavior.
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.
