Understanding Headless and Headed Mode in Playwright

Playwright is a powerful tool for automating browser interactions, offering two primary modes of operation: headless and headed. Understanding the difference between these modes can help you optimize your test environment and choose the right configuration for your project. In this article, we will dive into the key distinctions between headless and headed modes, and when to use each.

What Is Headless Mode?

In headless mode, a browser runs without a graphical user interface (GUI). This means that while the browser performs all actions such as loading pages, interacting with elements, and executing JavaScript, you won’t actually see the browser window. Headless mode is designed for automated testing, as it can run faster and consume fewer resources than headed mode.

Running in headless mode is ideal for:

• Automating large test suites where speed and performance are critical.
• Running tests in continuous integration (CI) pipelines where no GUI is needed.
• Testing applications that do not require visual verification or manual intervention.

What Is Headed Mode?

In headed mode, the browser runs with its full graphical interface. You can see the browser window as it navigates through pages, clicks elements, and interacts with the web application. This mode is often used for debugging purposes or when manual verification of test actions is necessary.

Running in headed mode is ideal for:

• Debugging tests by visually seeing how the browser interacts with the page.
• Manually verifying test steps, such as ensuring that UI elements render correctly.
• Demonstrating test execution to stakeholders or team members during development.

How to Switch Between Headless and Headed Mode in Playwright

Playwright allows you to easily switch between headless and headed modes depending on your needs. By default, Playwright runs in headless mode, but you can change this behavior by setting the headless option to false.

Here’s how to launch a browser in headless mode (default):

const { chromium } = require('playwright');
(async () => {
    const browser = await chromium.launch(); // headless by default
    const page = await browser.newPage();
    await page.goto('https://example.com');
    await browser.close();
})();

To run the browser in headed mode, simply set the headless option to false:

const { chromium } = require('playwright');
(async () => {
    const browser = await chromium.launch({ headless: false }); // headed mode
    const page = await browser.newPage();
    await page.goto('https://example.com');
    await browser.close();
})();

Performance and Use Cases

The choice between headless and headed modes depends on the specific requirements of your test or automation task. Headless mode is typically faster because it doesn't render the UI, making it suitable for CI pipelines and automated test suites. Headed mode, on the other hand, provides visual feedback, which is useful for debugging and validating UI changes.

Use headless mode when:

• You need to run tests as quickly as possible.
• You’re running tests in a CI environment without a display.
• The tests don’t require manual observation or UI verification.

Use headed mode when:

• You need to visually debug the tests.
• You want to manually verify UI changes or animations.
• You’re demonstrating the test execution to others.

Conclusion

Understanding when to use headless or headed mode in Playwright can significantly impact the performance and outcome of your browser tests. While headless mode is optimal for speed and automation, headed mode is essential for visual debugging and manual verification. By leveraging both modes, you can create a robust testing strategy that meets the needs of your project, whether you're running tests in a CI pipeline or debugging issues locally.