Headed Mode in Playwright

Introduction

In the previous article, we discussed the efficiency of headless testing. However, even the most seasoned automation engineer relies on Headed Mode when building and debugging their test suites. Headed mode allows you to see the browser in action, helping you visualize the flow, catch CSS issues, and understand why an element isn't being clicked.

Playwright's headed mode is not just a visual luxury—it's a critical tool in the development lifecycle of any automated test. In this guide, we'll dive into how to use it effectively and when you should switch from the "fast and invisible" to "slow and visible."

---

What is Headed Mode?

Headed mode simply means running your automation scripts in a standard browser window that is visible on your screen. You can watch Playwright open the URL, click buttons, fill out forms, and navigate through your application just like a real user would.

When to Use Headed Mode:

1. Initial Development: When writing a new test, seeing the interaction in real-time is invaluable for building reliable locators.
2. Debugging: If a test is failing in your headless CI environment but you can't figure out why, running it locally in headed mode is often the first step to diagnosis.
3. Internal Demonstrations: Showing stakeholders how a test suite works is much more effective when they can see it moving on the screen.
4. Complex Interactions: For things like drag-and-drop or hover effects, visual confirmation ensures your logic is sound.

---

How to Enable Headed Mode in Playwright

Playwright offers several ways to trigger headed execution.

1. Via Command Line (Recommended)

You can run any test in headed mode instantly:

npx playwright test --headed

To run only a specific file:

npx playwright test tests/login.spec.ts --headed

2. Global Configuration

If you're in the middle of a heavy development sprint, you might want to enable it globally in playwright.config.ts:

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

export default defineConfig({
  use: {
    headless: false,
  },
});

3. Launching a Single Browser Headed

If you're using Playwright as a library (outside of the test runner):

const { chromium } = require('playwright');
const browser = await chromium.launch({ headless: false });

---

Mastering the "SlowMo" Feature

When running in headed mode, Playwright can often move faster than the human eye can track. To better understand what's happening, you can use the slowMo option. This adds a delay (in milliseconds) after every action.

use: {
  headless: false,
  launchOptions: {
    slowMo: 1000, // 1 second delay between actions
  },
},

---

Debugging Workflow: Combining Headed Mode with Playwright Inspect

If headed mode isn't enough, you can combine it with the Playwright Inspector. This tool allows you to step through your test line-by-line while watching the browser window.

npx playwright test --debug

This command will open the Inspector window along with the headed browser. You can pause, play, and even explore locators directly on the page.

---

Best Practices for Headed Execution

While headed mode is powerful, keep these tips in mind:

• Don't Forget CI: Never leave your global config set to headless: false when pushing to Git. Your CI runners will likely fail because they don't have a display output (X11/Display Server).
• Use Dedicated Profiles: Avoid using your personal browser profile to prevent extensions or saved passwords from interfering with tests.
• Stay Focused: If you interact with the headed browser window while the test is running (like clicking or resizing), you might cause the test to fail.

---

Conclusion

Headed mode is your window into the mind of Playwright. It’s an essential part of the development and debugging process, providing the visual feedback needed to build high-quality automation. In 2026, where web applications are more dynamic than ever, being able to quickly switch between headless efficiency and headed precision is a hallmark of a great automation engineer.

---