How to Run Tests in Playwright Headless Chrome? [2026]

Running Playwright tests in headless mode often feels like the obvious choice. You get faster execution and a setup that works well in CI without opening a browser window for every test.

But a passing headless test does not always reflect how the same flow behaves in the Chrome version your users run. Playwright may use bundled Chromium and the lack of a visible UI can also affect certain browser behaviors.

I see headless testing as one part of the testing setup rather than a replacement for real browser testing. This article looks at how the environments differ and when you should verify important flows in real Chrome.

What is a Headless Chrome

Headless Chrome is a mode of the Chrome browser that runs without a visible graphical interface. In this mode, all browser operations occur in the background, allowing scripts and automated tests to execute faster while consuming fewer system resources.

In Playwright, headless Chrome can use either a lightweight chromium-headless-shell for speed or the full Chrome binary for accurate rendering. Developers can switch between headless and headed modes via configuration, CLI flags, or programmatic launch options.

UI Differences Breaking Headless Tests?

Headless Chrome renders elements differently. Test on real devices to find UI shifts and missing elements.

Test on Real Devices

What Happens Behind a Headless Test Run

Playwright runs Chrome in headless mode by default, allowing automated tests and scripts to execute faster and consume fewer system resources. Understanding this process will help you optimize tests and control browser behavior effectively.

Step 1: Launching the Browser

Playwright begins by starting a Chrome instance in headless mode, either using a lightweight shell or the full Chrome binary.

• Default Headless Launch: Running npx playwright test automatically launches Chrome in headless mode.

• Browser Binary Selection: By default, Playwright uses a chromium-headless-shell for speed, but the full Chrome binary can be used for more accurate rendering.

Step 2: Creating a Browser Context

Each test runs in an isolated browser context to ensure separation between tests and maintain consistent state.

• Isolation: Each context has its own cookies, cache, and storage.
• Performance Advantage: Contexts allow multiple tests to run without starting a full browser each time, saving resources.

Step 3: Launch Options

Now, you can customize headless behavior when launching Chrome programmatically.

• headless: true | false to enable or disable headless mode.
• channel: ‘chromium’ to use the full Chrome binary instead of the headless shell.
• args: […] to pass custom flags for
• debugging or network configuration.

Step 4: Interacting with Pages

Once the browser is running, Playwright opens pages (tabs) and controls them through its API without showing the UI.

• Perform actions like clicking buttons, filling forms, and navigating URLs programmatically.

• Scripts interact with the page as if a user were performing the actions, while the browser remains in the background.

Step 5: Closing the Browser

After tests complete, Playwright closes the headless browser automatically to free resources.

Pages or contexts can also be closed explicitly to release memory in long-running test suites.

Tests can be run in headed mode for visual debugging without changing the scripts.

Ways to Control Headless Execution

Playwright runs tests headlessly by default, but you can control this behavior depending on how you run your tests. You can switch modes from the command line, set a project-wide default, or choose the browser channel when launching it programmatically.

1.  Switch Modes from the CLI

Running the test command normally uses headless mode:

npx playwright test

When you need to watch the test run for debugging, add –headed:

npx playwright test --headed

2. Set the Default in Your Configuration

If you want the same behavior across your test suite, define it in playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({

  use: {

    headless: true,

  },

});

Change headless to false when you want the browser UI to open during test runs.

3. Choose the Browser When Launching Programmatically

If you are using the Playwright library directly, you can control headless mode through launch():

const browser = await chromium.launch({

  headless: true

});

One important correction to the original example: channel: ‘chromium’ does not mean full Google Chrome. To run installed Chrome, specify the Chrome channel:

const browser = await chromium.launch({

  channel: 'chrome',

  headless: true

});

This distinction matters when you specifically want to test against Google Chrome rather than Playwright’s bundled Chromium.

4. Create Isolated Browser Contexts

Once the browser is running, you can create separate browser contexts for isolated test sessions:

const context = await browser.newContext();

const page = await context.newPage();



await page.goto('https://example.com');

Each context gets its own cookies and storage. In Playwright Test, this isolation is already handled for you by default, so you generally do not need to create contexts manually for every test.

What Playwright Adds to a Headless Browser Session

When Playwright launches a browser, it is not simply opening Chrome and leaving it alone. It communicates with the browser to perform actions and observe what happens during the test. Most of the time, you do not need to think about this layer. It becomes relevant when you are comparing automated test results with behavior you see during normal browser use.

• Actions happen under Playwright’s control: Before clicking or typing, Playwright checks whether an element is ready for the action. A test therefore does not interact with the page in exactly the same way as raw browser automation or a person clicking manually.
• Browser events are available to your test: Network requests, console messages, downloads, dialogs, and other events can be observed through Playwright APIs. This is what makes detailed debugging possible without manually opening DevTools.
• The browser environment still matters: A difference you see between headless and headed runs should not automatically be blamed on Playwright. The browser channel, browser version, operating system, viewport, and headless mode can all affect the result.
• Debugging can change the conditions: Pausing a test or running it slowly gives the page more time to settle. If a test only passes while debugging, look for timing or synchronization problems rather than assuming the issue has disappeared.

The practical takeaway is to treat a headless test result as evidence from a specific automated environment. When something behaves differently in the browser your users run, reproduce it in that same browser and environment before deciding where the problem comes from.

How Headless Chrome Differs from Headed Chrome in Playwright

Headless Chrome runs without a visible user interface, while headed Chrome shows the browser UI during test execution. Both modes behave similarly, but there are key differences in performance, rendering, and debugging capabilities.

Here is a table highlighting the main differences:

Where Headless Test Runs Can Behave Differently

You may first notice a problem when a test passes in headed mode but fails as soon as it runs in CI. The test code has not changed, yet an element appears too late or a visual check produces a different result. Headless execution can expose differences that are easy to miss when you only test with a visible browser.

Here are a few areas worth checking when that happens:

• Rendering looks different: Fonts, animations, and dynamically rendered content may not always appear exactly as they do in your local headed session. If you run visual tests, keep the test environment consistent before comparing screenshots.
• Timing issues suddenly appear: Headless tests can run under different resource and timing conditions. Instead of adding fixed waits, check whether the test is properly waiting for the state it actually needs.
• Some browser features need extra setup: Downloads, permissions, media playback, and other browser capabilities may depend on your browser configuration or test environment. Check these settings when a flow works locally but fails elsewhere.
• You cannot watch the failure happen: Without a visible browser, the final error may not tell you enough. Screenshots and traces can help you see what the page looked like and what happened before the test failed.

Best Practices for Running Playwright Tests in Headless Chrome

To ensure reliable and efficient test execution in headless Chrome, it is important to follow certain best practices. These guidelines help avoid common pitfalls and maintain test consistency across local and CI/CD environments.

• Explicit Waits and Assertions: Avoid relying solely on default timeouts. Use explicit waits and robust Playwright assertions to prevent race conditions caused by faster headless execution.

• Use Full Chrome Binary When Needed: For tests requiring precise rendering, animations, or media playback, use the full Chrome binary (channel: ‘chromium’) instead of the lightweight headless shell.
• Enable Tracing and Screenshots: Capture traces, screenshots, or video recordings during headless runs to debug failures when no UI is visible.

• Optimize Resource Usage: Limit the number of concurrent contexts and pages to avoid memory or CPU issues, especially in CI/CD pipelines with limited resources.
• Replicate CI/CD Environment Locally: Match fonts, libraries, and screen resolutions locally to detect issues before running tests in headless CI/CD environments.
• Test in Headed Mode When Debugging: Switch to headed mode (–headed or headless: false) for visually debugging test failures, then return to headless for automation.
• Handle External Dependencies: Ensure third-party scripts, CAPTCHAs, or modals are accounted for, as they may behave differently in headless mode.

UI Differences Breaking Headless Tests?

Headless Chrome renders elements differently. Test on real devices to find UI shifts and missing elements.

Test on Real Devices

Taking Headless Tests Closer to Real User Environments

Running Playwright tests in headless Chrome is fast and efficient, but it does not fully replicate how real users experience websites or applications. Differences in rendering, browser behavior, or device-specific quirks can cause tests to pass in headless mode yet fail in production.

Testing on real browsers and devices ensures higher accuracy, captures edge cases, and validates that automation scripts reflect actual user experiences.

Platforms like BrowserStack provide access to a wide range of real devices and browsers, allowing developers to execute Playwright tests in environments that closely match production. This helps teams identify rendering issues, functionality problems, or device-specific inconsistencies that headless tests alone may miss.

These features help validate Playwright tests:

• Real Device Cloud: Run important test flows on the device models and OS versions your users actually have instead of assuming a desktop browser run covers every environment.
• Parallel Testing: Check the same test suite across several browser and device combinations at once. You get broader coverage without waiting for each environment to finish one after another.
• Local Environment Testing: Test applications that are still in development or only accessible within your private network. You can catch environment-specific issues before the application is publicly available.
• Test Reporting & Analytics: See which tests are failing and where those failures occur. Having results across different environments makes it easier to spot whether an issue is isolated to a particular browser or device.
• Web Performance Testing: Check how your application performs under different browser and device conditions. This gives you a better view of the experience beyond whether a test simply passes or fails.

Talk to an Expert

Conclusion

Headless mode is a practical choice when you need fast test runs and regular feedback in CI. But a passing headless test only tells you what happened in that particular browser environment.

The better approach is to use headless execution for everyday automation and bring in real browser testing where it matters most. Knowing which browser is actually running and verifying critical flows in user environments gives you much more confidence in what your tests are telling you.

Try BrowserStack for Free