Recommended Free Tools
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Playwright runs browsers headlessly by default, so no window appears. To show the browser UI in a direct script, launch the browser with headless: false:
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('https://example.com');
await page.waitForTimeout(3000);
await browser.close();
})();The same launch option works with Firefox and WebKit. If you are using Playwright Test, use npx playwright test --headed for one visible run, or set use.headless to false in your test configuration.
What “headed” means in Playwright
Headless mode runs a browser without displaying its window. It is efficient for automated jobs, but it hides the page while you develop or diagnose a test. Headed mode starts a normal visible browser window that you can watch while Playwright performs actions.
Showing the window does not change the basic Playwright API. Navigation, locators, assertions, contexts and tracing work the same way. It only changes how the browser is rendered. A graphical desktop session is required; a server, container or CI runner without a display cannot show a local window unless you provide a suitable display or use a remote UI arrangement.
#1 Best Overall
Show the window in a direct Playwright script
JavaScript
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({
headless: false
});
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await page.waitForTimeout(5000); // optional: keep the window visible
await browser.close();
})();The browser remains visible until your script closes it or the process exits. In a real test, replace the fixed delay with a meaningful action or assertion; a delay is useful only when you need time to observe the page.
Slow the actions down for demonstrations
const browser = await chromium.launch({
headless: false,
slowMo: 100
});slowMo adds a delay to Playwright operations, making clicks and typing easier to follow. It is independent of visibility: headless: false displays the window, while slowMo changes the speed of actions.
TypeScript
import { chromium } from 'playwright';
const browser = await chromium.launch({ headless: false, slowMo: 100 });
const page = await browser.newPage();
await page.goto('https://example.com');
await page.screenshot({ path: 'page.png' });
await browser.close();Firefox or WebKit
import { firefox, webkit } from 'playwright';
const firefoxBrowser = await firefox.launch({ headless: false });
await firefoxBrowser.close();
const webkitBrowser = await webkit.launch({ headless: false });
await webkitBrowser.close();Use the browser type that matches the behavior you are investigating. A headed run in one engine does not prove that another engine renders identically.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Show the window for a Playwright Test run
One test run
From the project directory, run:
npx playwright test --headedThis enables headed mode for that invocation without changing your checked-in configuration. You can combine it with a file, project, test title or other Playwright Test filters.
Make headed mode the default
In playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
headless: false
}
});Playwright Test’s headless setting defaults to true. Setting it to false applies to test runs that use this configuration. You can still override the behavior for a particular command or project when needed.
JavaScript configuration
const { defineConfig } = require('@playwright/test');
module.exports = defineConfig({
use: {
headless: false
}
});Choose between headed, debug and UI modes
| Method | Use it when | What it adds |
|---|---|---|
headless: false |
A direct library script needs a visible browser. | Only the browser window. |
npx playwright test --headed |
You want one visible Test-runner execution. | Headed browser for that command. |
use.headless: false |
Most test runs in a project should be visible. | Persistent headed configuration. |
npx playwright test --debug |
You need step-by-step debugging. | Headed mode, PWDEBUG=1, disabled timeout, one worker and a stop after the first failure. |
npx playwright test --ui |
You want Playwright’s visual test interface. | UI Mode with actions, timeline, DOM snapshots, logs, errors and network activity. |
--ui is not another name for a visible browser. It opens Playwright’s test interface; the browser itself can still require headed configuration. Use --headed for simple visibility and --debug or --ui when their additional inspection features solve your problem.
A practical debugging workflow
- Run the smallest relevant test with
npx playwright test path/to/test.spec.ts --headed. - Watch the page at the point where navigation, a locator or an assertion fails.
- If timing is hard to follow, add
slowMoto a direct launch or use--debugfor Test. - Use Playwright’s locator and assertion output rather than inserting many arbitrary sleeps.
- For a broader inspection of actions, snapshots, logs and network requests, rerun with
npx playwright test --ui. - Restore headless execution for unattended CI unless the CI environment is deliberately configured for a display.
Headed browsers in Docker, Codespaces and remote machines
A visible window must have somewhere to be displayed. On a normal desktop, launching with headless: false is sufficient. In a container or hosted development environment, there may be no local graphical session.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Playwright UI Mode documents exposing its interface with:
npx playwright test --ui --ui-host=0.0.0.0Binding a UI endpoint to all network interfaces can expose traces, passwords and other secrets to machines that can reach the endpoint. Use it only on a protected network, add appropriate access controls, and avoid exposing it publicly. This setting exposes the Playwright UI service; it does not magically create a physical monitor inside a container.
For CI, prefer screenshots, videos, traces and test reports when you need evidence of a run. If you truly need a headed browser, configure a desktop/display service appropriate to that runner and verify that the browser process can connect to it.
Browser channels and headless differences
Playwright normally uses a regular Chromium build for headed operation and a separate headless shell for its default headless mode. The documented newer Chromium headless mode is selected through the chromium channel. Chrome and Edge headless behavior can therefore differ from the default headless shell.
When a bug appears only in headless mode, compare the exact browser type and channel, not just the headless Boolean. Record the Playwright version, browser channel, operating system and launch options so another developer can reproduce the same combination.
Troubleshooting headed mode
No window appears
- Confirm the direct launch contains
headless: false, or that the Test command includes--headed. - Check that you are not editing a configuration file that the command does not load.
- Make sure the script has not immediately closed the browser or exited before navigation.
- Verify that the process is running in a graphical session. A headless server cannot display a desktop window by itself.
The test still behaves headlessly
Check which interface you are using. chromium.launch() receives options in its launch object. Playwright Test receives --headed on the command line or headless: false under use. Setting a property in the wrong place has no effect.
The window opens and closes immediately
The browser lifetime follows your process. Add a real assertion or action, or temporarily add await page.waitForTimeout(5000) while observing. Do not leave a long fixed delay in a production test merely to keep a window open.
Actions are too fast to see
Add a modest slowMo value to a direct launch, or run the test with --debug. Slow motion is for observation and diagnosis, not a general replacement for reliable waits.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsUI Mode is reachable by other machines
If you used --ui-host=0.0.0.0, treat the endpoint as sensitive. Restrict network access, use a private tunnel or protected environment, and shut it down after debugging. Traces and pages can contain credentials or personal data.
Headed and headless results differ
Compare viewport, device settings, browser channel, permissions, extensions, environment variables and timing. A visible run may also change available fonts, GPU behavior or display dimensions. Capture the exact launch and project settings before drawing conclusions.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is a clean image or PDF rather than watching Playwright interact with a page, ScreenshotNeo provides a single HTTP request: ScreenshotNeo is a website screenshot API and MCP server.
It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed; each response reports the page verdict and billing status in X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info and capture_pdf tools 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 minutecURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)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}`);See the complete parameter reference in the ScreenshotNeo documentation. Options include full-page captures with lazy images loaded, CSS-selector element shots, dark mode, device presets, custom viewports, retina scale, PDF paper settings and page ranges, custom CSS and JavaScript, clicks before capture, selector waits, network-idle waits, ad and tracker blocking, custom headers and cookies, authorization, timezone and geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification.
Plans include 1,000 screenshots per month free with no card, then Starter at $5 for 3,000, Growth at $15 for 15,000, Pro at $39 for 60,000, Scale at $99 for 250,000 and Business at $249 for 1,000,000. Yearly billing provides two months free, and every feature is available on every plan. Create a free ScreenshotNeo account to start with the 1,000 monthly screenshots.
Frequently Asked Questions
Does headed mode change the selectors or assertions I write?
No. It changes browser presentation; your Playwright actions, locators and assertions use the same APIs.
Can I show a browser window in a CI job?
Only if the runner provides a graphical display or an equivalent remote desktop setup. Otherwise collect traces, videos, screenshots or reports instead.
Should I use headed mode for every automated test?
Usually no. Keep unattended runs headless for efficiency and use headed, debug or UI Mode when developing and diagnosing failures.
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.
