Headless vs Headed Mode?

The Answer

Headless mode (default) runs the browser without a visible window — faster and required for CI. Headed mode opens a visible browser — essential for debugging and test development.

Deep Dive Explanation

In modern Chromium, there are two headless modes: 'old' headless (a separate browser binary) and 'new' headless (same Chrome binary, just no window). Playwright uses the new headless mode by default for Chromium, which behaves identically to headed Chrome — eliminating headless-specific rendering bugs.

example.spec.ts

// playwright.config.ts - environment-aware config
export default defineConfig({
  use: {
    headless: !process.env.HEADED, // headless by default, headed when HEADED=1
  },
});

// CLI options:
// npx playwright test              → headless (default)
// npx playwright test --headed     → headed (shows browser)
// npx playwright test --debug      → headed + Inspector + slowMo

// Performance comparison:
// Headless: ~30-60% faster (no rendering overhead)
// Headed: slower but lets you SEE what the test does

// When to use headed:
// - Writing new tests (visual verification)
// - Debugging failures (use page.pause())
// - Recording codegen scripts