How to Enable Expert Mode for Advanced Debugging in Zendriver

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 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 (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:

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) 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:

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:

# 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:

// 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.
• It injects a shadow DOM override script through Connection._prepare_expert in 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.

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