Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsRun a JavaScript or TypeScript Playwright test with npx playwright test --headed. The command keeps the normal Playwright Test workflow but opens the browser so you can watch each action. For a permanent setting, add use: { headless: false } to playwright.config.ts. The sections below cover one-off runs, test filters, debugging modes, Python, Linux CI, troubleshooting, and a browser-free screenshot alternative.
Run a Playwright Test With the Browser Visible
From your project root, run:
npx playwright test --headedPlaywright Test is headless by default. The --headed flag changes browser visibility for that run; it does not turn the test into an interactive, step-by-step session. You will see the configured browser open, navigate, click, type, and close as the test executes. Playwright describes this as a way to “visually see how Playwright interacts with the website” in its running and debugging tests documentation.
Run the command from the directory containing your Playwright configuration and tests. If the project uses another package manager, use its equivalent runner:
yarn playwright test --headed
pnpm exec playwright test --headedIf the browsers have not been installed on the machine, install the browser binaries with your project’s normal Playwright installation procedure before running the test. The exact installation command depends on how the project was created and which Playwright version it uses.
#1 Best Overall
Limit the Headed Run to the Test You Need
Watching an entire suite can be slow. Add the same file, project, and title filters you use for an ordinary Playwright Test run.
Run one test file
npx playwright test tests/example.spec.ts --headedThe file path can be relative to the project root. Put the flag before or after the file argument; Playwright accepts both as command-line options.
Choose a configured browser project
npx playwright test --project=chromium --headedReplace chromium with a project name that exists in playwright.config.ts, such as another browser project in your configuration.
Filter by test title
npx playwright test -g "checkout rejects an expired card" --headedThe -g option selects tests whose titles match the supplied pattern. Combining filters is useful when a failure occurs only in one browser or one spec file:
Recommended Free Tools
npx playwright test tests/checkout.spec.ts --project=chromium -g "expired card" --headedMake Headed Mode the Default
For a local debugging project where you usually want to see the browser, configure it instead of adding the flag every time:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
headless: false,
},
});Playwright’s documented default for headless is true. Setting it to false makes normal npx playwright test runs headed unless a command-line option, project setting, or another configuration layer changes the value. Keep the setting local if your continuous-integration jobs should remain headless.
Choose Between Headed, Debug, and UI Mode
These three workflows all make Playwright more observable, but they solve different problems.
| Workflow | How to start it | What you get | Best use |
|---|---|---|---|
| Headed run | npx playwright test --headed |
A normal test run with a visible browser window. | Watch the complete flow without pausing for manual steps. |
| Debug mode | npx playwright test --debug |
Browser windows plus the Playwright Inspector, step controls, and locator exploration. Tests run one by one and the default timeout is set to zero. | Stop at actions, inspect locators, and advance through a failure interactively. |
| UI Mode | npx playwright test --ui |
An interactive test browser with test selection, watch behavior, traces, and per-action information. | Explore a suite, rerun selected tests, and inspect trace details while developing. |
Use --headed when visibility is enough. Use --debug when you need to pause and inspect a step. Use --ui when selecting tests and examining traces is more useful than a plain command-line run.
Binding UI Mode in a container
When UI Mode runs inside a container or remote environment, Playwright documents options such as --ui-host=0.0.0.0 and an optional --ui-port. Binding to all interfaces can make traces, passwords, and other secrets available to machines on the network. Prefer a protected tunnel or a local-only binding, and expose UI Mode only when you understand who can reach that port.
Python Tests Use the Pytest Plugin Syntax
Python projects using the Playwright pytest plugin do not use the JavaScript/TypeScript Playwright Test runner command. The plugin’s headed invocation is:
pytest --headedYou can choose a browser at the same time:
pytest --browser webkit --headedThe pytest plugin’s command-line options configure its default browser, context, and page fixtures. They do not automatically change browser, context, or page objects that your test creates directly through the Playwright API. If a test launches its own objects, configure that code explicitly.
Headed Execution on Linux CI
A Linux build agent normally has no desktop display. Playwright’s CI guidance says headed execution on Linux requires Xvfb, a virtual X display server. The documented pattern is:
Free tools Windows power users keep installed
One-click scans. No signup required.
xvfb-run npx playwright testUse the same command-line filters with the wrapped command when needed:
xvfb-run npx playwright test tests/example.spec.ts --project=chromiumCheck that the runner image includes Xvfb and the browser’s required system dependencies. The command cannot create missing packages, and third-party CI images do not all contain the same display libraries. A typical display error indicates that DISPLAY is unset or that Xvfb is unavailable.
For ordinary CI validation, headless execution avoids the virtual-display requirement. Reserve Xvfb and headed mode for jobs where seeing the browser is part of diagnosis or another explicit requirement.
What Headed Mode Changes—and What It Does Not
- It changes visibility: the browser window is rendered to a desktop display or virtual display.
- It preserves the test runner: test discovery, projects, retries, assertions, reporters, and filters still come from your normal Playwright Test command.
- It does not add pauses: the test continues immediately unless your code waits, an action blocks, or you choose debug mode.
- It can require display resources: a local desktop or Xvfb is needed on Linux agents.
A headed run is therefore useful for observing behavior, but it is not a substitute for tracing or Inspector controls when you need to examine a precise action.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Troubleshoot Common Problems
The command says that Playwright is not found
Run it from the project that has Playwright installed and use the package manager’s executor (npx, yarn playwright, or pnpm exec playwright). If the dependency is absent, add Playwright through the project’s normal package installation process, then install its browser binaries.
No browser window appears on Linux
On a desktop, verify that the session has a working display. On CI or a container, run the test under Xvfb:
xvfb-run npx playwright test --headedIf this fails, inspect the image for Xvfb and the operating-system dependencies required by the selected browser.
The window opens and closes too quickly
That is expected after the test finishes. Narrow the run with a file or -g filter, add --debug for Inspector-controlled pauses, or use UI Mode to select and replay a test.
Python’s --headed option has no effect
Confirm that the test is using the Playwright pytest plugin and that the browser was obtained from its default fixtures. The plugin’s CLI settings do not apply to objects created directly with API calls.
UI Mode is reachable by other machines
A host of 0.0.0.0 listens on all network interfaces. Because traces can contain credentials and page data, bind locally or protect remote access with your network controls. Do not expose a debugging port simply to make the interface easier to reach.
The headed job is unreliable in a minimal container
Separate display problems from test problems. First confirm Xvfb starts and the browser dependencies are installed; then run a single spec headed. Once the display works, add projects and the rest of the suite. This isolates environment failures from locator or application failures.
Performance, Reliability, and Workflow Choices
A visible browser consumes display resources and may be less convenient for parallel CI workers than headless execution. Headed mode is most valuable when a human needs to observe navigation, timing, popups, or a failure’s visual state. For repeatable automated checks, keep the normal headless job and add a focused headed or debug job for diagnosis.
For a reliable investigation:
- Reproduce the failure with the smallest file or title filter.
- Run the same project headed so the browser, viewport, and configuration match the failing job.
- Switch to
--debugif you need to pause before the failing action. - Use UI Mode when you need test selection, watch behavior, or trace inspection across several attempts.
- After fixing the test, rerun the original headless command to verify that the result is not dependent on a local display.
Playwright’s live documentation can change independently of your installed package, and the cited guidance does not establish a fixed Playwright release for these flags. Check the documentation and your installed version when writing version-specific automation.
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 of a web page rather than an interactive test, ScreenshotNeo returns it through one HTTP request. It accepts cookie and consent banners before capture, removes more than 60 known consent platforms along with newsletter popups and chat widgets, and lets you turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; the response identifies the result with X-Page-Verdict and X-Billed headers.
Use the API documentation at https://screenshotneo.com/docs/ for authentication and options. This is a screenshot service, not a replacement for Playwright’s assertions or browser interaction tests.
cURL
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}`);ScreenshotNeo also supports full-page captures with lazy images loaded, CSS-selector element captures, dark mode, device presets and custom viewports, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, clicks before capture, selector or network-idle waits, request and resource blocking, custom headers, cookies, user agents, Authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Its parameter names are compatible with those used by many other screenshot APIs, which can simplify a migration.
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 matchWindows 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 reinstallThe Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing provides two months free. If you want screenshots without installing a browser or display server, create a free ScreenshotNeo account.
Frequently Asked Questions
Does --headed select a browser automatically?
No. It shows the browser selected by the active Playwright project. Use --project=... when you need a specific configured browser.
Can headed mode run in a container?
Yes, provided the container supplies a display. On Linux, the documented approach is to run the command through Xvfb, such as xvfb-run npx playwright test --headed.
What is the safest way to share UI Mode from a remote machine?
Avoid exposing it broadly. A network-wide bind can reveal traces and secrets; use local binding or a protected tunnel instead.
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 →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.
