How do you run Playwright tests headlessly vs headed?

The Answer

Playwright runs headless by default (no visible browser). Pass `--headed` CLI flag or set `headless: false` in config for a visible browser. Use `--debug` for headed mode with the Inspector attached.

Deep Dive Explanation

The `--debug` flag is more powerful than `--headed` alone: it also attaches the Playwright Inspector (a GUI for stepping through tests), enables step-by-step execution, and automatically applies `slowMo` to make actions visible. It's the recommended debugging mode.

example.spec.ts

// CLI options
// npx playwright test                  → headless (default, for CI)
// npx playwright test --headed         → headed (see browser)
// npx playwright test --debug          → headed + Playwright Inspector
// PWDEBUG=1 npx playwright test        → same as --debug

// Config-based
export default defineConfig({
  use: {
    headless: true,   // default
    // headless: false, // for debugging sessions
  },
});

// Environment-aware (common pattern)
export default defineConfig({
  use: {
    headless: process.env.CI === 'true', // headless in CI, headed locally
  },
});