Recommended Free Tools
Playwright starts browsers headlessly, so no window is visible. To show the browser, launch it with headless: false. For Playwright Test, use npx playwright test --headed for one run or set use: { headless: false } in your configuration.
Choose the right way to show the browser
The correct setting depends on whether you are launching Playwright directly or running tests through Playwright Test.
| Situation | Use | What it does |
|---|---|---|
| Direct script | browserType.launch({ headless: false }) |
Shows the browser window for that script. |
| One Playwright Test run | npx playwright test --headed |
Runs tests with visible browsers without changing project files. |
| Every Test run | use: { headless: false } |
Makes headed mode the default in the selected Playwright Test configuration. |
| Interactive debugging | npx playwright test --debug |
Enables headed mode, disables the timeout, uses one worker, and pauses for inspection. |
| Visual test interface | npx playwright test --ui |
Opens Playwright UI Mode, where you can inspect tests, traces, DOM snapshots, logs, errors, and network activity. |
--debug and --ui are more than simple visibility switches. Use --headed when you only need to see the browser; choose the other modes when you also need their debugging interface.
Show the browser in a direct Playwright script
Install Playwright and a browser
In a new Node.js project, install the library and browser binaries:
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 errors#1 Best Overall
npm init -y
npm install -D playwright
npx playwright installThe launch option belongs in the object passed to chromium.launch(), firefox.launch(), or webkit.launch(). Playwright’s default is headless mode; setting the value to false displays the window.
Minimal headed Chromium script
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());
// Keep the window open until you finish observing it.
await page.waitForTimeout(3000);
await browser.close();
})();Run it with node headed.js. The browser remains visible while the script is active. If the script reaches browser.close() immediately, the window may appear only briefly; use an explicit wait, a real interaction, or a debugger breakpoint when you need time to inspect it.
A safer script with cleanup
Use try/finally so a failed navigation does not leave a browser process running:
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: false, slowMo: 100 });
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await page.getByRole('link', { name: 'More information...' }).click();
await page.waitForTimeout(2000);
} finally {
await browser.close();
}
})();slowMo delays Playwright operations so a person can follow clicks and typing. It is optional and is not required to make the window visible. Keep it small or remove it for normal runs because every action takes longer.
Crashes, 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 minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallUse Firefox or WebKit
The same launch option works with the other Playwright browser types:
const { firefox, webkit } = require('playwright');
const firefoxBrowser = await firefox.launch({ headless: false });
await firefoxBrowser.close();
const webkitBrowser = await webkit.launch({ headless: false });
await webkitBrowser.close();In real code, place these statements inside an async function and close each browser in a finally block. A headed run uses the browser’s normal graphical window, so the machine executing the script must have a display available.
Run Playwright Test with a visible browser
One-off headed run
From the project directory, append --headed to the normal test command:
npx playwright test --headedYou can still select files, projects, or tests with the usual Playwright Test arguments. The flag changes the browser mode for that invocation and does not rewrite your configuration.
Make headed mode the project default
Set headless: false inside the use section of playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
headless: false,
},
});The Playwright Test default is true, so omitting the property returns the project to headless execution. A command-line --headed run is useful when you want temporary visibility without committing this setting.
Example test
import { test, expect } from '@playwright/test';
test('homepage has the expected heading', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveTitle(/Example Domain/);
});Run the test visibly with npx playwright test --headed. The browser is controlled by the test runner and closes when the test finishes.
Use debug mode or UI Mode when visibility is not enough
Debug one test interactively
npx playwright test --debugThe debug shortcut sets PWDEBUG=1, enables headed mode, disables the normal timeout, stops after one failure, and uses one worker. It is useful when you need to pause, inspect locators, or step through actions rather than merely watch them.
Free tools Windows power users keep installed
One-click scans. No signup required.
Open the Playwright visual test runner
npx playwright test --uiUI Mode is a separate application from the browser window. It provides a test list, timeline, DOM snapshots, logs, errors, and network information. A UI Mode window does not imply that the test browser is headed; use --headed as well when you specifically need the page’s browser chrome and rendered window.
Using UI Mode in Docker or Codespaces
For a remote development environment, Playwright documents exposing UI Mode with:
npx playwright test --ui --ui-host=0.0.0.0Binding to 0.0.0.0 makes the interface reachable from other machines. Protect the endpoint and use it only on a trusted network: traces, passwords, tokens, and other secrets visible in the UI could otherwise be exposed.
Make sure the execution environment can display a window
headless: false requests a graphical browser; it cannot create a physical monitor where none exists. A local desktop normally satisfies this requirement. A server, container, continuous-integration worker, or SSH session may have no display, in which case the browser can fail to start or be impossible to see from your computer.
- Run the headed command on a machine with a desktop session when you need to watch it.
- For unattended CI, keep tests headless unless your CI environment deliberately provides a protected graphical display.
- When working remotely, distinguish the browser window from UI Mode: UI Mode can be exposed over a network, while a headed page window belongs to the machine running the browser.
If the browser opens and disappears instantly, check whether the script exits immediately. Add a meaningful assertion, a breakpoint, or a temporary page.waitForTimeout(); do not use a long delay in production tests as a substitute for synchronization.
Understand browser channels and headless differences
Playwright uses a regular Chromium build for headed operation and a separate headless shell for its default headless mode. The browser guide also documents a newer Chrome-like headless mode through the chromium channel. Chrome and Edge channels can therefore behave differently from the default headless shell. If a test is sensitive to rendering, extensions, codecs, or browser-specific behavior, record the browser type and channel you use and verify the same combination in development and CI.
Changing to headed mode is not a substitute for choosing the correct browser channel. It changes whether a window is shown; it does not make all channels identical.
Troubleshooting headed Playwright runs
| Symptom | Likely cause | Fix |
|---|---|---|
| No window appears | The script or test is still headless. | Use headless: false, --headed, or the configured use.headless property. Confirm you are editing the configuration actually used by the command. |
| The window flashes and closes | The test completed or the script called browser.close(). |
Add a breakpoint, inspect during a failing step, or temporarily wait before cleanup. |
| Launch fails on a server | No graphical display is available. | Run on a desktop session or use a CI setup that provides a protected display. Headed mode cannot show a local window through a plain SSH terminal. |
--headed has no effect |
The command is not invoking Playwright Test, or an npm script is swallowing arguments. | Run npx playwright test --headed directly, then update the script so arguments are forwarded correctly. |
| UI Mode opens but the page browser is invisible | --ui starts the test interface; it does not itself request a headed browser. |
Add --headed when you need both interfaces. |
| Actions are too fast to follow | Normal automation executes immediately. | Use a small slowMo value for direct launches, or use --debug for interactive pauses. Remove diagnostic delays from regular runs. |
| Rendering differs between modes | Headless shell, headed Chromium, and browser channels can use different implementations. | Pin the browser type and channel relevant to your product, then compare screenshots or assertions in that same mode. |
Performance and reliability considerations
- Headed mode consumes graphical resources and usually runs more slowly than headless mode. Use it for development, demonstrations, and diagnosis rather than every CI job.
slowMomultiplies the cost of each Playwright operation. It improves observability but does not improve synchronization or reliability.- Prefer web-first assertions and locator waits to arbitrary sleeps. A visible browser can make timing problems easier to see, but it does not remove race conditions.
- Close contexts and browsers in cleanup code. This prevents leftover windows and processes from affecting later tests.
- When comparing screenshots or UI behavior, keep the browser type, channel, viewport, device scale, and headed/headless mode consistent. A change in any of these can alter rendering.
Or skip the browser setup
If your goal is a clean image or PDF of a URL rather than interactive browser debugging, ScreenshotNeo provides a single-request screenshot API. Its consent step accepts cookie banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and every response reports the result with X-Page-Verdict and X-Billed headers.
See the ScreenshotNeo API documentation for all options. This cURL request saves a WebP image:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe equivalent Python call is:
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)In 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}`);ScreenshotNeo also offers an MCP server for AI agents such as Claude, Cursor, and other MCP clients, with take_screenshot, get_page_info, and capture_pdf tools. The Free plan includes 1,000 screenshots each month without a card; paid plans start at $5 for 3,000 screenshots. Every feature is included on every plan. Create a free ScreenshotNeo account to try it.
FAQ
Can I show the browser only for one test?
Yes. Keep the project configuration unchanged and run that test selection with npx playwright test --headed.
Does headed mode let me interact with the window manually?
The window is visible, but Playwright still controls it. Manual inspection is useful; interactive stepping is better handled with --debug.
Why would a screenshot differ after switching to headed mode?
Headed Chromium and Playwright’s default headless shell are different execution paths. Browser channel, viewport, scale factor, fonts, and display environment can also affect rendering.
Frequently Asked Questions
Can I show the browser only for one test?
Yes. Keep the project configuration unchanged and run that test selection with npx playwright test --headed.
Does headed mode let me interact with the window manually?
The window is visible, but Playwright still controls it. Manual inspection is useful; interactive stepping is better handled with --debug.
Why would a screenshot differ after switching to headed mode?
Headed Chromium and Playwright’s default headless shell are different execution paths. Browser channel, viewport, scale factor, fonts, and display environment can also affect rendering.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
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.
