Backends¶

wavexis supports two backends with feature parity on Chrome.

CDP backend (cdpwave)¶

The default backend. Uses the Chrome DevTools Protocol directly.

pip install wavexis[cdp]

All 100+ methods are supported natively.

BiDi backend (bidiwave)¶

WebDriver BiDi backend. Uses a combination of:

BiDi native commands — browsingContext.navigate, script.evaluate, storage.getCookies, etc.
JS workarounds — script.evaluate with JavaScript for DOM, CSS, service workers, animations, cache storage
CDP bridge — browser.cdp.sendCommand for Debugger, WebAuthn, WebAudio, Media, Cast, Bluetooth, performance profiling, accessibility, IndexedDB, HAR

pip install wavexis[bidi]

All 100+ methods are implemented. Methods that rely on the CDP bridge only work on Chrome — on Firefox, only native BiDi capabilities and JS workarounds are available.

BiDi implementation strategies¶

Strategy	Used for
BiDi native	Navigation, screenshots, tabs, cookies, contexts, dialogs, permissions, input, storage
JS workaround	DOM, CSS inspection, overlay, cache storage, service workers, animations
CDP bridge (Chrome only)	Performance profiling, accessibility, debug, HAR, IndexedDB, WebAuthn, WebAudio, Media, Cast, Bluetooth, security, downloads, extensions, preferences

Selecting a backend¶

Use the --backend global flag:

wavexis --backend cdp screenshot https://example.com -o out.png
wavexis --backend bidi screenshot https://example.com -o out.png

Checking installation¶

wavexis install-check

Output:

  cdp: 3.3.0
  bidi: 2.0.0

Listing available backends¶

wavexis backends

When to use which¶

CDP — Chrome/Edge only. Most direct protocol access. Best for debugging and profiling.
BiDi — Works with any WebDriver BiDi-compatible browser (Chrome, Firefox, Safari). Best for cross-browser automation. Falls back to CDP bridge for Chrome-specific features.

Graceful backend degradation¶

If the preferred backend cannot be created (e.g. dependency not installed), wavexis automatically falls back to the next available backend. This is handled by BackendManager.select_with_fallback():

# Prefers CDP, falls back to BiDi if cdpwave is not installed
wavexis screenshot https://example.com -o out.png

# Prefers BiDi, falls back to CDP if bidiwave is not installed
wavexis --backend bidi screenshot https://example.com -o out.png

This applies to both CLI commands and serve mode. The fallback only handles backend creation failures (e.g. ImportError). Browser launch failures are handled by each action's error handling.