Run Tests in Playwright Headless Chrome

Most teams assume running Playwright in headless Chrome is straightforward. Tests run faster, CI pipelines stay lightweight, and there is little reason to think about the browser once headless: true is set. For many workflows, headless execution becomes the default and is rarely questioned.

However, Chrome behaves differently when no UI is attached, Playwright injects its own control layer, and in many setups the browser under test is not Google Chrome at all, but bundled Chromium.

Headless Chrome in Playwright is a controlled execution environment, not the browser users run. Passing tests in CI only confirms behavior inside that environment. Issues that appear in real Chrome are often outside the conditions headless execution creates, including rendering paths, event timing, and browser features gated behind a visible UI.

In this article, I will explain how headless execution differs from real Chrome, why those differences matter, and how to ensure tests reflect real user behavior.

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

How Playwright Runs Chrome in Headless Mode

Playwright runs Chrome in headless mode by default, allowing automated tests and scripts to execute faster and consume fewer system resources. Understanding the process helps developers 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

Developers 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.

How to Run Google Chrome in Headless Mode Using Playwright

After understanding how Playwright launches Chrome in headless mode, developers can control the behavior explicitly for different workflows. Playwright provides multiple ways to run Chrome in headless mode, whether through the command line, configuration files, or programmatic scripts.

1. Using the CLI

By default, npx playwright test runs tests in headless mode. For debugging or visual verification, you can switch to headed mode.

# Run tests in headed mode for visual debugging

npx playwright test –headed

2. Using the Configuration File

You can set the default headless behavior across all tests in playwright.config.ts.

// Enable headless mode
use: { headless: true }
// Disable headless mode to show the browser UI
use: { headless: false }

3. Programmatically Launching Chrome

For more control, Chrome can be launched directly from scripts. You can choose headless or headed mode, or opt for the full Chrome binary for accurate rendering.

// Launch Chrome in headless mode
const browser = await playwright.chromium.launch({ headless: true });
// Launch Chrome in headed mode for debugging
const browser = await playwright.chromium.launch({ headless: false });
// Use the full Chrome binary for accurate rendering
const browser = await playwright.chromium.launch({ channel: ‘chromium’, headless: true });

4. Managing Contexts and Pages

Once Chrome is running, tests operate in isolated browser contexts. This ensures that cookies, cache, and storage do not interfere between tests.

const context = await browser.newContext();const page = await context.newPage();

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

How Playwright Instrumentation Affects Headless Chrome

Playwright adds an automation layer on top of Chrome to control browser actions and monitor behavior. This instrumentation can affect performance, rendering, and API interactions in headless mode.

• Event Tracking: Playwright listens to page events such as network requests, console logs, and DOM changes, which can slightly impact execution speed.
• Browser Modifications: The library injects scripts and manages internal protocols to enable features like auto-wait and Playwright selectors.
• Rendering Differences: Some subtle rendering or animation behaviors may differ from a fully headed Chrome due to optimizations in headless mode.
• Debugging Behavior: Instrumentation enables Playwright debugging features, like pause() and screenshot capture, even in headless mode.
• Resource Usage: Tracking and controlling browser events increases memory and CPU usage compared to a raw headless browser without instrumentation.

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

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:

Common Issues When Running Playwright with Headless Chrome

Running Chrome in headless mode can improve speed and resource usage, but it may introduce subtle issues that developers should be aware of. Understanding these helps prevent test failures and ensures consistent results across environments.

• Differences in Rendering: Some CSS animations, fonts, or dynamic content may behave differently in headless mode compared to headed Chrome.

• Timing and Race Conditions: Headless execution can be faster, which may expose race conditions or require additional waits in tests.
• Browser Feature Limitations: Certain APIs or browser features, like file downloads or media playback, may behave differently or require extra configuration in headless mode.
• Debugging Challenges: Without a visible UI, it is harder to visually trace issues; developers must rely on screenshots, traces, or logs.

• Resource Constraints in CI/CD: Headless tests can still fail if the CI environment has limited memory, CPU, or missing dependencies like fonts or graphics libraries.
• Third-Party Scripts and Popups: Some external scripts, CAPTCHAs, or modal popups may not trigger or behave differently in headless mode.

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

Why Run Playwright Headless Chrome Tests on Real Browsers and Devices

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: Test on a wide variety of physical devices, ensuring compatibility across models, OS versions, and screen sizes.
• Parallel Testing: Run multiple tests simultaneously across different browsers and devices to speed up execution and improve coverage.
• Local Environment Testing: Execute tests on applications hosted locally or behind firewalls to catch issues before deployment.
• Test Reporting & Analytics: Gain detailed insights into test results, failures, and trends to make debugging faster and more efficient.
• Web Performance Testing: Measure page load times, responsiveness, and other performance metrics under real-world conditions.

Talk to an Expert

Conclusion

Headless Chrome in Playwright delivers faster test execution, lower resource usage, and reliable automation for large test suites and CI/CD pipelines. Its lightweight, background operation enables teams to run extensive tests efficiently while still maintaining test accuracy and coverage across multiple scenarios.

BrowserStack extends headless testing to real-world environments by validating Playwright tests on actual browsers and devices. Its capabilities for network debugging, geolocation testing, simulating varied device conditions, and seamless CI/CD integration make it a practical solution for end-to-end testing beyond what headless Chrome alone can achieve.

Try BrowserStack for Free