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

> Debug Webwright runs with the --debug flag. Launch a headed browser with DevTools and inspect delays for effective troubleshooting.

- Repository: [Microsoft/Webwright](https://github.com/microsoft/Webwright)
- Tags: how-to-guide
- Published: 2026-06-25

---

**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`](https://github.com/microsoft/Webwright/blob/main/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`](https://github.com/microsoft/Webwright/blob/main/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`](https://github.com/microsoft/Webwright/blob/main/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`](https://github.com/microsoft/Webwright/blob/main/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:

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

```

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

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

```

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

```text
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`](https://github.com/microsoft/Webwright/blob/main/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`](https://github.com/microsoft/Webwright/blob/main/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`](https://github.com/microsoft/Webwright/blob/main/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`](https://github.com/microsoft/Webwright/blob/main/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`](https://github.com/microsoft/Webwright/blob/main/src/webwright/environments/local_browser.py).