How to Debug Webwright Runs Using the `--debug` Flag and Headed Browser Mode

Passing the --debug flag to the Webwright CLI launches a headed browser with Chrome DevTools open, inserts a 250ms delay between actions, and keeps the browser window open after execution for manual inspection.

Webwright, Microsoft's open-source browser automation framework, provides a comprehensive debugging mode that requires no YAML configuration changes. When troubleshooting complex web interactions or inspecting page state during execution, this single CLI flag transforms headless automation into an interactive debugging session.

What the --debug Flag Configures

When you invoke run_one with debug=True, the framework automatically merges five developer-friendly settings into the environment configuration. These are defined in src/webwright/run/cli.py and applied to the LocalBrowser environment.

Debug Setting	Value	Effect
headless	False	Launches the browser with a visible UI window instead of running in the background.
devtools	True	Automatically opens the Chrome DevTools panel upon browser launch.
keep_open_on_exit	True	Prevents the browser from closing immediately after the script finishes executing.
prompt_before_close	True	Displays a console prompt requiring user input before the browser closes.
slow_mo_ms	250	Injects a 250 millisecond delay between automation actions to make execution easier to follow.

These settings are passed to LocalBrowser.prepare in src/webwright/environments/local_browser.py, which forwards them to Playwright's chromium.launch method.

How Debug Mode Works Under the Hood

The debugging experience is implemented through a five-stage pipeline that bridges the CLI interface to the browser lifecycle.

CLI Parsing – Typer registers the --debug option in src/webwright/run/cli.py as typer.Option(False, "--debug", help="Launch headed local Playwright …"). When present, this sets debug=True for the execution context.

Run Preparation – The run_one function constructs a temporary configuration dictionary. At lines 70-77, it conditionally injects the debug-specific keys into the "environment" section when debug=True.

Environment Creation – get_environment reads the merged configuration from src/webwright/environments/__init__.py and instantiates a LocalBrowser environment with the debug parameters.

Browser Launch – LocalBrowser.prepare calls Playwright's chromium.launch with headless=False, devtools=True, and slow_mo=250. The headless flag explicitly disables headless mode, while the other parameters configure the developer experience.

Lifecycle Handling – After the agent completes its task, env.close() checks keep_open_on_exit and prompt_before_close. If either is True, the browser context remains active until you press Enter in the console or close the window manually.

Practical Usage Examples

To execute a task in standard headless mode, use the standard run command:

webwright run -t "summarize the homepage of example.com"

To debug the same task with full visibility and interactive controls, append the --debug flag:

webwright run -t "summarize the homepage of example.com" --debug

When the task completes, you will see the following prompt in your terminal:

Press ENTER to close the browser…

The browser window remains open with the final page state visible, allowing you to inspect elements using DevTools before pressing Enter to terminate the session.

Key Source Files

Understanding the implementation requires familiarity with these specific modules:

• src/webwright/run/cli.py – Defines the --debug Typer option and implements the run_one function that injects debug configuration at lines 70-77.

• src/webwright/environments/local_browser.py – Translates environment configuration into Playwright launch arguments and manages browser lifecycle, including the close method that respects keep_open_on_exit.

• src/webwright/tools/persistent_local_browser.py – Provides the persistent Chromium subprocess that respects the headless argument flipped by the debug flag.

• src/webwright/run/doctor.py – Validation utility to verify local environment setup before debugging; useful for troubleshooting installation issues that might affect headed browser launches.

Summary

• The --debug flag is the single entry point for enabling interactive debugging in Webwright runs.
• It forces headed browser mode (headless=False) and automatically opens Chrome DevTools for real-time inspection.
• Execution automatically slows down by 250ms between actions to make automation steps visible and traceable.
• The browser stays open after script completion with a console prompt, enabling manual verification of the final page state.
• All configuration is handled programmatically in run_one and LocalBrowser, requiring no manual file edits.

Frequently Asked Questions

How do I enable debug mode in Webwright?

Pass the --debug flag to any webwright run command. The framework automatically configures the headed browser, opens DevTools, and sets appropriate delays without requiring changes to your configuration files.

What is the difference between headed and headless mode in Webwright?

Headless mode runs the browser in the background without a visible window, which is the default for production automation. Headed mode launches an actual browser window that you can see and interact with, which is essential for debugging UI interactions and visual state changes.

Why does my browser window stay open after the script finishes when using --debug?

This occurs because the debug flag sets keep_open_on_exit=True and prompt_before_close=True in the environment configuration. The LocalBrowser.close method checks these flags and pauses execution until you press Enter in the terminal, giving you time to inspect the final page state.

Can I adjust the slow motion delay when debugging Webwright runs?

The default delay is hardcoded to 250ms (slow_mo_ms=250) in the run_one function when debug mode is active. To use a different delay, you would need to modify the environment configuration directly or create a custom environment that overrides this value in src/webwright/environments/local_browser.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}