# How to Enable Expert Mode for Advanced Debugging in Zendriver

> Unlock advanced debugging in Zendriver by enabling expert mode. Set expert=True in the Config constructor for permissive Chrome flags and shadow DOM inspection.

- Repository: [CDP Driver/zendriver](https://github.com/cdpdriver/zendriver)
- Tags: how-to-guide
- Published: 2026-02-27

---

**Enable expert mode by setting `expert=True` in the `Config` constructor to unlock permissive Chrome flags and shadow DOM inspection capabilities.**

Zendriver is a Python library for browser automation built on the Chrome DevTools Protocol (CDP). When you need to **enable expert mode for advanced debugging**, you unlock specialized features designed for deep inspection of web applications, including cross-origin frame access and shadow DOM visibility.

## What Expert Mode Enables

Activating expert mode modifies how Zendriver launches and interacts with Chrome. The configuration triggers two distinct behavioral changes that relax security boundaries for debugging purposes.

### Permissive Chrome Flags

When `expert=True`, Zendriver automatically appends two critical command-line arguments to the Chrome launch sequence:

- **`--disable-web-security`** – Disables same-origin policy restrictions, allowing you to inspect and interact with cross-origin frames and resources.
- **`--disable-site-isolation-trials`** – Disables site isolation, making it easier to debug across different domains within the same process.

According to the Zendriver source code, these flags are injected in `Config.__call__` at lines 107-108 in [`zendriver/core/config.py`](https://github.com/cdpdriver/zendriver/blob/main/zendriver/core/config.py) when `self.expert` evaluates to true.

### Shadow DOM Override

Expert mode injects a helper script into every new page that forces all shadow roots to use **open mode**, making the full DOM structure visible to the DevTools protocol. This override is implemented in `Connection._prepare_expert` within [`zendriver/core/connection.py`](https://github.com/cdpdriver/zendriver/blob/main/zendriver/core/connection.py) (lines 52-68).

The script overrides `Element.prototype.attachShadow` to ensure `{ mode: 'open' }` is always applied, and it enables the **Page** CDP domain to facilitate script injection on new document loads.

## How to Enable Expert Mode in Your Code

You can activate expert mode during configuration initialization or dynamically before launching the browser.

### Via Config Constructor

The most common approach is to pass `expert=True` when instantiating the `Config` class:

```python
from zendriver.core.browser import Browser
from zendriver.core.config import Config

# Create a config with expert mode enabled

cfg = Config(expert=True)

# Launch browser with debugging features unlocked

browser = await Browser(cfg).launch()

# Open a page – permissive flags and shadow DOM override are now active

page = await browser.new_tab()
await page.goto("https://example.com")

```

This approach ensures that `Config.__init__` (lines 70-74 in [`zendriver/core/config.py`](https://github.com/cdpdriver/zendriver/blob/main/zendriver/core/config.py)) stores the expert flag before any browser processes start.

### Dynamically After Creation

You can also toggle expert mode on an existing configuration object, provided you do so before the first CDP command executes:

```python
cfg = Config()          # Default configuration

cfg.expert = True       # Enable expert mode dynamically

browser = await Browser(cfg).launch()

```

When `Connection.send` is first called, it automatically invokes `_prepare_expert` if the flag is set to true, injecting the shadow DOM script and enabling the Page domain.

## Verifying Expert Mode is Active

After launching the browser, you can confirm that expert mode features are functioning correctly.

### Checking Chrome Arguments

Inspect the configuration output to verify the permissive flags are present:

```python

# Display the full argument list passed to Chrome

print(cfg())

# Expected output includes:

# ['--disable-web-security', '--disable-site-isolation-trials', ...]

```

This confirms that `Config.__call__` successfully appended the security-relaxing flags.

### Inspecting the Shadow DOM Injection

Open the developer console in the launched browser and execute:

```javascript
// Verify the shadow DOM override is active
console.log(Element.prototype.attachShadow.toString());
// Expected output contains:
// "return this._attachShadow({ mode: 'open' });"

```

If the output matches, `Connection._prepare_expert` successfully injected the script that forces all shadow roots into open mode.

## Summary

- **Expert mode** unlocks advanced debugging by setting `expert=True` in the `Config` constructor.
- It adds **permissive Chrome flags** (`--disable-web-security` and `--disable-site-isolation-trials`) via `Config.__call__` in [`zendriver/core/config.py`](https://github.com/cdpdriver/zendriver/blob/main/zendriver/core/config.py).
- It **injects a shadow DOM override** script through `Connection._prepare_expert` in [`zendriver/core/connection.py`](https://github.com/cdpdriver/zendriver/blob/main/zendriver/core/connection.py), forcing all shadow roots to open mode.
- You can enable expert mode **statically at initialization** or **dynamically** before the first CDP command.
- Verify activation by checking the Chrome argument list or inspecting `Element.prototype.attachShadow` in the browser console.

## Frequently Asked Questions

### How do I enable expert mode for advanced debugging in Zendriver?

Set `expert=True` when creating a `Config` instance: `cfg = Config(expert=True)`. This activates permissive Chrome flags and injects the shadow DOM override script automatically when the browser launches.

### What security implications does expert mode have?

Expert mode disables critical browser security features including same-origin policy (`--disable-web-security`) and site isolation (`--disable-site-isolation-trials`). Only use expert mode in isolated, local debugging environments and never on production systems or when handling sensitive data.

### Can I toggle expert mode after the browser has already started?

No, you must set `cfg.expert = True` before calling `Browser(cfg).launch()`. The expert mode preparations in `Connection._prepare_expert` execute on the first CDP command sent to the browser, so the flag must be set prior to any browser interaction.

### How can I verify that expert mode is actually working?

Check the Chrome launch arguments by printing `cfg()` and confirming the presence of `--disable-web-security` and `--disable-site-isolation-trials`. Additionally, open the browser's developer console and run `console.log(Element.prototype.attachShadow.toString())` to verify the script injection that forces shadow roots to open mode.