# https://github.com/seleniumbase/SeleniumBase Project Manual

Generated at: 2026-06-22 06:05:49 UTC

## Table of Contents

- [Framework Overview and Core Architecture](#page-1)
- [Stealth, UC Mode, and CDP Mode](#page-2)
- [Testing Patterns, pytest, and BDD Examples](#page-3)
- [Console Scripts, Recorder, and Developer Tools](#page-4)

<a id='page-1'></a>

## Framework Overview and Core Architecture

### Related Pages

Related topics: [Stealth, UC Mode, and CDP Mode](#page-2), [Testing Patterns, pytest, and BDD Examples](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/seleniumbase/SeleniumBase/blob/main/README.md)
- [seleniumbase/__init__.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/__init__.py)
- [seleniumbase/__version__.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/__version__.py)
- [seleniumbase/__main__.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/__main__.py)
- [seleniumbase/core/browser_launcher.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/core/browser_launcher.py)
- [seleniumbase/core/sb_driver.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/core/sb_driver.py)
- [integrations/node_js/package.json](https://github.com/seleniumbase/SeleniumBase/blob/main/integrations/node_js/package.json)
</details>

# Framework Overview and Core Architecture

## Purpose and Scope

SeleniumBase is a Python-based test automation framework that wraps Selenium WebDriver with additional utilities for browser testing, scraping, and bypassing common anti-bot challenges. It is published as a Python package and ships with a CLI entry point, integration examples, and optional browser-mode subsystems that extend the base WebDriver functionality.

The framework's role is to provide a single, consistent API surface that abstracts away the differences between running tests locally, in CI, headlessly, or against hardened (anti-bot) sites. It supports pytest discovery, a built-in `BaseCase` class, the `SB` context manager, the `DriverContext` context manager, the Recorder/MasterQA tools, and several optional "modes" (UC Mode, CDP Mode, Wire Mode) that are activated via CLI flags or constructor arguments. Source: [README.md](https://github.com/seleniumbase/SeleniumBase/blob/main/README.md).

## Core Architecture

The framework is organized around a layered architecture: a public Python API at the top, a core driver/launcher layer in the middle, and a browser-specific mode layer at the bottom. Entry points are declared in the package's `__init__.py`, while the CLI entry is wired through `__main__.py`. The version is centrally managed in `__version__.py`, which is imported by both the package init and the CLI.

```mermaid
flowchart TB
    A[User Code: pytest / SB / BaseCase] --> B[Public API: seleniumbase/__init__.py]
    B --> C[Core: BaseCase, SB, DriverContext]
    C --> D[Driver Layer: sb_driver.py]
    C --> E[Launcher Layer: browser_launcher.py]
    E --> F{Browser Mode}
    F -->|default| G[Selenium WebDriver]
    F -->|--uc| H[UC Mode]
    F -->|--wire| I[Wire Mode: selenium-wire]
    F -->|--cdp| J[CDP Mode]
    D --> G
    H --> G
    I --> G
    J --> G
    G --> K[(Browser Process)]
```

The driver layer (`seleniumbase/core/sb_driver.py`) is responsible for producing a configured `Driver` object, applying user options, and resolving the active browser mode. The launcher layer (`seleniumbase/core/browser_launcher.py`) is responsible for translating mode flags and capability dictionaries into the actual subprocess arguments used to start Chromium-based browsers, Firefox, or remote drivers. Source: [seleniumbase/core/sb_driver.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/core/sb_driver.py), [seleniumbase/core/browser_launcher.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/core/browser_launcher.py).

## Browser Modes and Subsystems

SeleniumBase exposes several optional subsystems, each toggled by a CLI flag or constructor argument. Community discussion frequently focuses on the trade-offs between these modes:

- **UC Mode** (`--uc`): Uses `undetected-chromedriver` to evade fingerprinting on Cloudflare and similar anti-bot services. Community issue #2865 documents that UC Mode saw major updates in `4.28.0` following a June 2024 Cloudflare change, and that subsequent work was superseded by CDP Mode. Source: [GitHub Issue #2865](https://github.com/seleniumbase/SeleniumBase/issues/2865).
- **CDP Mode**: A newer replacement that drives Chrome via the Chrome DevTools Protocol directly. See `examples/cdp_mode/ReadMe.md` referenced in the community thread.
- **Wire Mode** (`--wire`): Wraps requests through `selenium-wire` for network capture and rewriting. Community issue #2782 notes a dependency conflict: `selenium-wire` requires `blinker._saferef`, which was removed in newer `blinker` releases, so users installing `selenium-wire` alone can hit `No module named 'blinker._saferef'`. Source: [GitHub Issue #2782](https://github.com/seleniumbase/SeleniumBase/issues/2782).
- **Extension Loading**: Community issue #4053 documents that Chrome-branded Chromium removed `--load-extension` and its workaround flag in Chrome 142; this does not affect Chrome-for-Testing. Source: [GitHub Issue #4053](https://github.com/seleniumbase/SeleniumBase/issues/4053).

These modes are coordinated through the launcher; the public API does not change, so test code remains portable across modes.

## Node.js Integration and Entry Points

SeleniumBase ships an `integrations/node_js` directory that demonstrates how to consume the framework's HTTP endpoints from a Node.js application. The example uses Express as its web server:

```json
{
  "name": "app",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "start": "node ./bin/www"
  },
  "dependencies": {
    "express": "~4.21.0"
  }
}
```

Source: [integrations/node_js/package.json](https://github.com/seleniumbase/SeleniumBase/blob/main/integrations/node_js/package.json).

The Node.js integration is intentionally minimal: it is a thin Express shell that proxies requests to a SeleniumBase-driven browser running in a separate process. The Python side remains authoritative; Node.js only provides the HTTP transport. The CLI entry point used to start that process is exposed via `seleniumbase/__main__.py`, which delegates to `console_scripts` defined in the package configuration. Source: [seleniumbase/__main__.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/__main__.py).

## Versioning and Release Cadence

The current release line is `4.50.x`. The most recent release, `4.50.1`, shipped a layout fix for the SeleniumBase Recorder App (commit `77cb1e26`, PR #4405). Version metadata is sourced from `seleniumbase/__version__.py` and is the single source of truth used by both the Python package and the CLI banner. Source: [seleniumbase/__version__.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/__version__.py).

## Common Failure Modes

When working with SeleniumBase's core architecture, watch for these recurring issues:

| Symptom | Likely Cause | Reference |
|---|---|---|
| `No module named 'blinker._saferef'` | Newer `blinker` dropped the module that `selenium-wire` imports | Issue #2782 |
| UC Mode stops bypassing Cloudflare | Anti-bot vendor pushed fingerprinting updates | Issue #2865 |
| Extension fails to load in Chrome 142+ | `--load-extension` removed from Chrome-branded Chromium | Issue #4053 |
| Recorder UI misaligned | Layout regression (fixed in `4.50.1`) | PR #4405 |

Each of these is resolved within the launcher/driver layer rather than in user test code, which is consistent with the framework's design goal of keeping the public API stable.

## See Also

- UC Mode usage and recent changes
- CDP Mode examples (`examples/cdp_mode/ReadMe.md`)
- Wire Mode and `selenium-wire` dependency pinning
- Recorder App and MasterQA tools
- CI/CD integration guides

---

<a id='page-2'></a>

## Stealth, UC Mode, and CDP Mode

### Related Pages

Related topics: [Framework Overview and Core Architecture](#page-1), [Testing Patterns, pytest, and BDD Examples](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [seleniumbase/undetected/__init__.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/undetected/__init__.py)
- [seleniumbase/undetected/cdp.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/undetected/cdp.py)
- [seleniumbase/undetected/patcher.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/undetected/patcher.py)
- [seleniumbase/undetected/dprocess.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/undetected/dprocess.py)
- [seleniumbase/undetected/reactor.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/undetected/reactor.py)
- [seleniumbase/undetected/options.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/undetected/options.py)
- [examples/cdp_mode/ReadMe.md](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/cdp_mode/ReadMe.md)
</details>

# Stealth, UC Mode, and CDP Mode

SeleniumBase provides three distinct approaches to launching browsers that avoid bot detection: **UC Mode** (undetected-chromedriver), **CDP Mode** (Chrome DevTools Protocol), and ad-hoc **Stealth** techniques. These capabilities exist because modern websites — particularly those protected by Cloudflare and similar services — actively fingerprint automation tools and block them. This page documents the architecture, usage patterns, and known limitations of each approach based on the source code in the `seleniumbase/undetected/` package.

## Overview and Purpose

The `seleniumbase/undetected/` package wraps and patches a Chromium-based driver so that automation traffic is harder to distinguish from a regular user. The `__init__.py` module exposes the high-level `Chrome` class, which is the entry point for both UC Mode and the newer CDP Mode.

```python
# Source: seleniumbase/undetected/__init__.py
from seleniumbase.undetected.cdp import CDP
from seleniumbase.undetected.dprocess import start_detached
```

- **UC Mode** relies on patching the `chromedriver` binary in memory and launching a hidden Chrome subprocess. It is controlled by the `uc` / `uc_cdp` arguments on `Driver` and is the original stealth mechanism in SeleniumBase. Community issue [#2865](https://github.com/seleniumbase/SeleniumBase/issues/2865) discusses how Cloudflare's June 2024 update forced major changes here.
- **CDP Mode** attaches to an already-running Chrome instance over the Chrome DevTools Protocol. It is the modern recommended approach because it does not require a custom driver binary and survives upstream Chromium changes. It is documented in [examples/cdp_mode/ReadMe.md](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/cdp_mode/ReadMe.md).
- **Stealth** is the umbrella term for the patches applied to make the driver look like a normal Chrome install. The `patcher.py` module handles binary rewriting, while `options.py` injects flags that strip automation markers.

## UC Mode Architecture

UC Mode works by downloading, patching, and re-launching `chromedriver` so that automation-only CDP variables (`$cdc_…`) are renamed and Selenium-injected JavaScript is removed. The flow is implemented across four cooperating modules.

```mermaid
graph TD
    A[User calls uc=True] --> B[undetected/__init__.py Chrome class]
    B --> C[undetected/patcher.py]
    C --> Patches[Patches chromedriver binary]
    Patches --> D[undetected/dprocess.py]
    D --> E[Detached subprocess]
    E --> F[undetected/reactor.py]
    F --> G[Selenium WebDriver session]
```

Key responsibilities:

- **`patcher.py`** downloads a matching `chromedriver`, locates the `$cdc_` variables inside the binary, and rewrites them with random strings. This defeats the most common detection signal.
- **`dprocess.py`** starts the patched driver in a detached process so that closing the parent Python script does not kill Chrome.
- **`reactor.py`** handles the asynchronous handshake between Selenium commands and the running browser.
- **`options.py`** appends Chromium flags such as `--disable-blink-features=AutomationControlled` to mask the `navigator.webdriver` flag.

### UC Mode Usage

```python
from seleniumbase import Driver

with Driver(uc=True) as driver:
    driver.get("https://nowsecure.nl")
    driver.uc_click("div.cf-turnstile")
    driver.sleep(3)
    driver.save_screenshot("uc_result.png")
```

UC Mode gained three major improvements documented in issue [#2865](https://github.com/seleniumbase/SeleniumBase/issues/2865): a new `uc_cdp` argument for finer control, automatic driver re-patching when Cloudflare's fingerprint changes, and a `reconnect()` helper that re-establishes the CDP session after a block.

### Known UC Mode Limitations

Community issue [#4053](https://github.com/seleniumbase/SeleniumBase/issues/4053) reports that **Chrome 142 removed the `--load-extension` option** and its `--disable-features=DisableLoadExtensionCommandLineSwitch` workaround. Because UC Mode historically relied on bundled extensions (e.g. `XPathLab`, `Recorder`) injected via `--load-extension`, this Chromium change broke some UC workflows. Chrome-for-Testing builds are unaffected, so the recommended mitigation is to pin a Chrome-for-Testing binary when running UC Mode on Chrome 142+.

## CDP Mode Architecture

CDP Mode is a lighter alternative introduced after UC Mode's ongoing maintenance burden became apparent. Instead of patching `chromedriver`, CDP Mode connects to a user-launched Chrome instance via the WebSocket-based Chrome DevTools Protocol. The `cdp.py` module encapsulates the low-level `pychrome` client.

```python
# Source: seleniumbase/undetected/cdp.py
class CDP:
    """Thin wrapper around pychrome for sending CDP commands."""
    def __init__(self, url: str = "http://127.0.0.1:9222"):
        self._browser = pychrome.Browser(url=url)
```

The workflow is:

1. Launch Chrome with `--remote-debugging-port=9222` (manually or via the `open_cdp_browser` helper).
2. Call `Driver(cdp=True)`, which causes SeleniumBase to skip the local driver and instead forward Selenium commands to the running browser over CDP.
3. Use `driver.cdp.select` / `driver.cdp.send` for low-level DevTools calls when the high-level Selenium API is insufficient.

### Why CDP Mode Is Now Preferred

The README at [examples/cdp_mode/ReadMe.md](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/cdp_mode/ReadMe.md) and the discussion in issue [#2865](https://github.com/seleniumbase/SeleniumBase/issues/2865) note that most of the information about UC Mode is "out-of-date due to the newer CDP Mode." The advantages are:

- **No binary patching** — survives Chrome upgrades without SeleniumBase releases.
- **Lower detection surface** — the WebSocket connection is indistinguishable from a regular debugging session.
- **Reuses an existing browser** — the user can sign into accounts, accept cookies, and configure extensions once, then automate over CDP.

## Stealth Techniques and Configuration

Stealth in SeleniumBase is the combination of flags and JS shims applied regardless of mode. `options.py` is the central registry:

| Flag | Purpose |
|------|---------|
| `--disable-blink-features=AutomationControlled` | Hides `navigator.webdriver` |
| `--disable-infobars` | Suppresses the "Chrome is being controlled" banner |
| `--no-first-run` | Skips the first-run wizard |
| `--no-default-browser-check` | Skips the default-browser prompt |
| `--start-maximized` | Uses a realistic viewport |
| `--user-data-dir=<temp>` | Isolates automation cookies from the real profile |

These flags are merged with any user-supplied `chromium_arg` list before the driver is launched. The `Driver` constructor exposes `agent`, `locale`, `proxy`, and `headless` parameters that complement the stealth flags and are applied through `options.py` so that the same code path works in UC Mode, CDP Mode, and regular mode.

## Choosing Between the Three Modes

| Mode | When to use | Failure mode to watch for |
|------|-------------|---------------------------|
| **Regular** | Sites without bot protection | Detected as automation on hardened sites |
| **UC Mode** | Cloudflare / similar turnstile challenges | Breaks when Chrome removes flags UC depends on (see #4053) |
| **CDP Mode** | Long-running automation, account-bound sessions | Requires Chrome to be launched with `--remote-debugging-port` |
| **Stealth flags** | Add-on to any mode | Not sufficient alone against advanced fingerprinting |

For new projects, start with **CDP Mode** and add **Stealth flags**. Fall back to **UC Mode** only when a target site specifically rejects CDP-attached sessions. Always pin a Chrome-for-Testing build if you need the `--load-extension` workaround on Chrome 142+.

## See Also

- [UC Mode video tutorial series](https://www.youtube.com/watch?v=5dMFI3e85ig) (referenced in issues #2478 and #3000)
- Issue #2865 — *Major updates have arrived in 4.28.0 (mostly for UC Mode)*
- Issue #4053 — *Chrome 142 removed the --load-extension option*
- [examples/cdp_mode/ReadMe.md](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/cdp_mode/ReadMe.md) — official CDP Mode walkthrough
- [seleniumbase/undetected/patcher.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/undetected/patcher.py) — binary-patching internals
- [seleniumbase/undetected/options.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/undetected/options.py) — flag registry

---

<a id='page-3'></a>

## Testing Patterns, pytest, and BDD Examples

### Related Pages

Related topics: [Framework Overview and Core Architecture](#page-1), [Stealth, UC Mode, and CDP Mode](#page-2), [Console Scripts, Recorder, and Developer Tools](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [examples/ReadMe.md](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/ReadMe.md)
- [examples/my_first_test.py](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/my_first_test.py)
- [examples/test_get_swag.py](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/test_get_swag.py)
- [examples/boilerplates/base_test_case.py](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/boilerplates/base_test_case.py)
- [examples/boilerplates/boilerplate_test.py](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/boilerplates/boilerplate_test.py)
- [examples/boilerplates/sb_fixture_test.py](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/boilerplates/sb_fixture_test.py)
</details>

# Testing Patterns, pytest, and BDD Examples

SeleniumBase is a Python test framework that wraps Selenium WebDriver and extends it with pytest integration, a BDD-style runner, and a curated set of helpers. The repository ships a catalog of example tests under [`examples/`](https://github.com/seleniumbase/SeleniumBase/tree/main/examples) that demonstrate the recommended patterns for writing browser-driven tests. This page documents those patterns, the boilerplate templates that ship with the project, and the BDD (Behavior-Driven Development) workflow that the framework supports.

## 1. Overview of the Examples Directory

The `examples/` directory is the canonical entry point for new users. It is organized so that a first-time visitor can read [`examples/ReadMe.md`](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/ReadMe.md) and immediately locate a runnable demonstration for almost every framework feature. Source: [examples/ReadMe.md:1-200]()

Typical categories exposed in the readme include:

| Category | Purpose |
|----------|---------|
| `examples/` | End-to-end test scripts using the `BaseCase` API |
| `examples/boilerplates/` | Reusable templates for `unittest`, pytest, and fixture styles |
| `examples/cdp_mode/` | Tests that drive Chromium DevTools Protocol (per issue #2865) |
| `examples/uc_mode/` | Tests that exercise UC Mode (undetected-chromedriver) |

This catalog is the single most important reference for understanding how SeleniumBase expects tests to be structured.

## 2. Basic pytest Patterns

### 2.1 Minimal test script

The simplest pattern uses a class that inherits from `BaseCase` and defines `test_*` methods that pytest can collect automatically. The [`examples/my_first_test.py`](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/my_first_test.py) file demonstrates this style. Source: [examples/my_first_test.py:1-40]()

A typical minimal test performs four steps inside a single method:

1. `self.open(url)` — navigate to a page
2. `self.assert_element(selector)` — verify presence
3. `self.update_text(selector, value)` — interact with a form
4. `self.click(selector)` — submit or navigate

Because the parent class is a `unittest.TestCase` subclass, the test is simultaneously discoverable by both pytest and the built-in `unittest` runner.

### 2.2 Multi-step scenario

[`examples/test_get_swag.py`](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/test_get_swag.py) is a more realistic example that walks through a complete purchase flow on a demo e-commerce site. Source: [examples/test_get_swag.py:1-150]() It uses helper methods such as `self.assert_text_visible()`, `self.assert_no_js_errors()`, and `self.sleep()` to validate page state at each step.

### 2.3 Pytest fixtures

[`examples/boilerplates/sb_fixture_test.py`](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/boilerplates/sb_fixture_test.py) shows the recommended fixture-based style. Source: [examples/boilerplates/sb_fixture_test.py:1-60]() The pattern uses a module-level `driver` fixture that yields a configured `BaseCase` instance and performs teardown automatically. This is preferred when tests need to share expensive setup such as authenticated sessions.

## 3. Boilerplate Templates

The `examples/boilerplates/` directory contains three starter templates that new users can copy directly into a project. Source: [examples/ReadMe.md:50-90]()

| Boilerplate | Base Class | Use Case |
|-------------|------------|----------|
| `boilerplate_test.py` | `BaseCase` | Standard pytest/unittest hybrid |
| `base_test_case.py` | Custom subclass | When project needs a project-wide base with shared helpers |
| `sb_fixture_test.py` | Fixture | When tests should be plain functions, not classes |

### 3.1 The `BaseCase` inheritance pattern

`boilerplate_test.py` inherits from `BaseCase` and exposes all SeleniumBase methods (`self.click`, `self.type`, `self.assert_element`, etc.) on every test. Source: [examples/boilerplates/boilerplate_test.py:1-40]() The advantage is discoverability: IDE autocomplete shows every available action as soon as `self` is typed inside a test method.

### 3.2 Project-wide base class

`base_test_case.py` demonstrates how to layer project-specific helpers on top of `BaseCase`. Source: [examples/boilerplates/base_test_case.py:1-80]() A common pattern is to define a `MyBaseTest(BaseCase)` that overrides `setUp()` to inject site URLs, credentials, or preconfigured `data` objects. Tests then import `MyBaseTest` instead of `BaseCase`, keeping the public API stable even as the base evolves.

## 4. BDD-Style Examples

SeleniumBase provides a built-in BDD runner that interprets Gherkin syntax (Given/When/Then) and steps are matched against `@given` / `@when` / `@then` decorated methods on a steps class. Although the BDD examples live in a separate `examples/bdd/` directory referenced from the readme, the conventions are consistent with the rest of the framework. Source: [examples/ReadMe.md:100-140]()

### 4.1 Recommended workflow

1. Write `.feature` files using standard Gherkin.
2. Implement a `StepDefs` class whose methods reference `self` (the live `BaseCase` instance).
3. Run with `seleniumbase run feature_file.feature`.

The same `BaseCase` API used in pytest scripts is available inside step methods, so the learning curve is minimal for anyone who has already written a `BaseCase` test.

### 4.2 When to choose BDD over pytest

| Criterion | pytest (`BaseCase`) | BDD |
|-----------|---------------------|-----|
| Audience | Engineers | Mixed (QA, PM, engineers) |
| Readability | Python source | Gherkin English |
| Reuse | Class inheritance | Step method composition |
| Tooling | pytest plugins | `seleniumbase run` |

## 5. Running Tests and Common Options

Tests are normally executed via the SeleniumBase CLI, which forwards arguments to pytest. Useful flags include:

- `pytest my_first_test.py --browser=chrome` — choose a browser
- `pytest -v --headless` — run without a UI
- `pytest --html=report.html` — generate an HTML report
- `pytest --uc` / `--cdp` — enable UC Mode or CDP Mode (see community issue #2865 for the migration story from UC to CDP Mode)

## 6. Known Pitfalls

A few patterns cause confusion and appear in the issue tracker:

- **Wire Mode dependency drift.** Issue #2782 reports `No module named 'blinker._saferef'` when `selenium-wire` is installed without the correct `blinker` version. Pin `blinker<1.7` or use the bundled `--wire` extras. Source: community issue #2782.
- **UC Mode vs. CDP Mode.** As called out in issue #2865, UC Mode has been superseded for many use cases by the newer CDP Mode example set; new code should prefer the CDP Mode examples.
- **Extension loading on Chrome 142+.** Issue #4053 notes that `--load-extension` was removed in Chrome 142, so any test relying on a custom extension must switch to Chrome-for-Testing.

## See Also

- [SeleniumBase on GitHub](https://github.com/seleniumbase/SeleniumBase)
- [examples/ReadMe.md](https://github.com/seleniumbase/SeleniumBase/blob/main/examples/ReadMe.md)
- [CDP Mode examples](https://github.com/seleniumbase/SeleniumBase/tree/main/examples/cdp_mode)
- [UC Mode examples](https://github.com/seleniumbase/SeleniumBase/tree/main/examples/uc_mode)

---

<a id='page-4'></a>

## Console Scripts, Recorder, and Developer Tools

### Related Pages

Related topics: [Framework Overview and Core Architecture](#page-1), [Testing Patterns, pytest, and BDD Examples](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [seleniumbase/console_scripts/ReadMe.md](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/console_scripts/ReadMe.md)
- [seleniumbase/console_scripts/run.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/console_scripts/run.py)
- [seleniumbase/console_scripts/sb_recorder.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/console_scripts/sb_recorder.py)
- [seleniumbase/console_scripts/sb_commander.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/console_scripts/sb_commander.py)
- [seleniumbase/console_scripts/sb_behave_gui.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/console_scripts/sb_behave_gui.py)
- [seleniumbase/console_scripts/sb_caseplans.py](https://github.com/seleniumbase/SeleniumBase/blob/main/seleniumbase/console_scripts/sb_caseplans.py)
- [setup.py](https://github.com/seleniumbase/SeleniumBase/blob/main/setup.py)

</details>

# Console Scripts, Recorder, and Developer Tools

## 1. Overview and Purpose

SeleniumBase ships a collection of **console scripts** that augment the core test framework with developer-facing utilities: a web-based **Recorder** for capturing browser actions as Python code, a **Commander** utility, a **Behave GUI** for Behavior-Driven Development, and a **Case Plans** helper. These are exposed as command-line entry points when the package is installed.

Source: [seleniumbase/console_scripts/ReadMe.md:1-20]()

The scripts live under the `seleniumbase/console_scripts/` directory and are wired into the installable package via the `console_scripts` section of `setup.py`, which registers them as executable commands such as `sbase`, `sb_recorder`, `sb_commander`, `sb_caseplans`, and `sb_behave_gui`.

Source: [setup.py:console_scripts]()

| Command | Purpose | Source File |
| --- | --- | --- |
| `sbase` | Unified CLI for running tests, scripts, and helpers | [run.py]() |
| `sb_recorder` | Launch the browser-action recorder web app | [sb_recorder.py]() |
| `sb_commander` | Commander utility (advanced control) | [sb_commander.py]() |
| `sb_caseplans` | Generate and manage test case plans | [sb_caseplans.py]() |
| `sb_behave_gui` | Launch a GUI for `behave` BDD scenarios | [sb_behave_gui.py]() |

## 2. The `sbase` Unified Runner

The `run.py` module implements the `sbase` command, which acts as the central dispatch for SeleniumBase. It accepts subcommands such as `run`, `mkfile`, `objectify`, `print`, `extract`, `replay`, `upload`, `download`, and `convert`, redirecting each to the appropriate internal helper.

Source: [seleniumbase/console_scripts/run.py:1-50]()

A typical usage pattern is:

```bash
# Run a test file with the configured test runner
sbase run my_first_test.py

# Convert a recorded script into a full SeleniumBase test
sbase convert my_recorded_test.py
```

The unified entry point reduces the number of distinct commands a developer must remember and provides consistent help, argument parsing, and error reporting across subcommands.

## 3. The SeleniumBase Recorder (`sb_recorder`)

### 3.1 Purpose

The Recorder is a local web application that records user actions in a browser and emits equivalent SeleniumBase Python code. It is the most actively maintained developer tool in this group — the v4.50.1 release included a layout fix for the Recorder App UI.

Source: [seleniumbase/console_scripts/sb_recorder.py:1-30]()

### 3.2 Launching the Recorder

```bash
# Install SeleniumBase (includes the recorder)
pip install seleniumbase

# Launch the recorder
sb_recorder
```

By default, the recorder opens a local browser window with a side panel. The user interacts with the page, and the recorder emits click, type, assert, and select commands. The output is suitable for direct insertion into a `BaseCase` subclass.

### 3.3 Browser-Extension Dependency

The Recorder relies on a Chrome extension loaded via the `--load-extension` Chromium command-line switch. As reported in the community issue *#4053*, Chrome-branded Chromium removed `--load-extension` in Chrome 142, breaking this mechanism. The workaround `—disable-features=DisableLoadExtensionCommandLineSwitch` is no longer effective on Chrome-for-Testing is unaffected, and the Recorder's compatibility matrix reflects this constraint.

Source: Community Issue [#4053]() — *Chrome 142 removed the "--load-extension" option AND the workaround*.

### 3.4 Workflow

```mermaid
flowchart LR
    A[User launches sb_recorder] --> B[Browser opens with side panel]
    B --> C[User performs actions on target site]
    C --> D[Recorder captures events]
    D --> E[Generates SeleniumBase Python code]
    E --> F[User copies code into a test file]
    F --> G[sbase run test_file.py]
```

## 4. Other Developer Tools

### 4.1 `sb_commander`

The Commander utility provides a higher-level orchestration surface for advanced scenarios, including UC Mode and CDP Mode pre-checks. It is invoked when the user needs a guided command-builder rather than free-form CLI flags.

Source: [seleniumbase/console_scripts/sb_commander.py:1-20]()

### 4.2 `sb_behave_gui`

The Behave GUI wraps the `behave` BDD runner with a graphical interface, allowing non-technical stakeholders to browse feature files, select scenarios, and execute them without touching the command line.

Source: [seleniumbase/console_scripts/sb_behave_gui.py:1-20]()

### 4.3 `sb_caseplans`

The `sb_caseplans` tool scaffolds and maintains **test case plans** — structured documents that map requirements to test methods. It is useful for QA teams that need traceability between specifications and automation.

Source: [seleniumbase/console_scripts/sb_caseplans.py:1-20]()

## 5. Failure Modes and Troubleshooting

- **`ModuleNotFoundError: No module named 'blinker._saferef'`** — Triggered when Wire Mode (`--wire`) is enabled but `blinker` has been upgraded past the version that ships `blinker._saferef`, a transitive dependency of `selenium-wire`. Pin `blinker<1.7` or install a SeleniumBase release that vendors the compatible `selenium-wire`.

  Source: Community Issue [#2782]() — *Wire Mode: `No module named 'blinker._saferef'` if installing `selenium-wire` alone*.

- **Recorder extension fails to load on Chrome ≥ 142** — Switch to Chrome-for-Testing or an older Chromium build, or use the CDP Mode recorder path (see the *CDP Mode* examples directory).

  Source: Community Issue [#4053]().

- **`sbase` command not found after install** — Ensure that the Python environment's `bin/` (or `Scripts/` on Windows) is on `PATH`, and that the install completed without errors in the `console_scripts` registration step of `setup.py`.

  Source: [setup.py:console_scripts]()

## See Also

- [CDP Mode examples](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/cdp_mode/ReadMe.md)
- [UC Mode overview](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/uc_mode/ReadMe.md)
- [SeleniumBase Master ReadMe](https://github.com/seleniumbase/SeleniumBase/blob/master/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: seleniumbase/SeleniumBase

Summary: Found 35 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4247

## 2. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4394

## 3. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4400

## 4. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Chromium Warning: `Google API keys are missing. Some functionality of Chromium will be disabled.`
- User impact: Developers may misconfigure credentials, environment, or host setup: Chromium Warning: `Google API keys are missing. Some functionality of Chromium will be disabled.`
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4396

## 5. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4395

## 6. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4392

## 7. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4393

## 8. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/seleniumbase/SeleniumBase

## 9. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: 4.49.14 - Chromium overhaul with CDP Mode updates
- User impact: Upgrade or migration may change expected behavior: 4.49.14 - Chromium overhaul with CDP Mode updates
- Evidence: failure_mode_cluster:github_release | https://github.com/seleniumbase/SeleniumBase/releases/tag/v4.49.14

## 10. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: Missing `await` in `ad_block` option code led to `RuntimeWarning: coroutine 'Browser.wait' was never awaited`
- User impact: Developers may hit a documented source-backed failure mode: Missing `await` in `ad_block` option code led to `RuntimeWarning: coroutine 'Browser.wait' was never awaited`
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4388

## 11. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: Slider captcha no bypassed, stops before slider finishes
- User impact: Developers may hit a documented source-backed failure mode: Slider captcha no bypassed, stops before slider finishes
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4392

## 12. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: The latest chromium version makes UC Mode crash (includes UC + CDP Mode)
- User impact: Developers may hit a documented source-backed failure mode: The latest chromium version makes UC Mode crash (includes UC + CDP Mode)
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4393

## 13. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4388

## 14. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4399

## 15. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4392

## 16. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4401

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: "Can AI tools help you with web-scraping and CAPTCHA-bypass?" is now on YouTube
- User impact: Developers may hit a documented source-backed failure mode: "Can AI tools help you with web-scraping and CAPTCHA-bypass?" is now on YouTube
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4333

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: the new version of seleniumbase doesnt fully load chromium and crashes whenever i run my python code
- User impact: Developers may hit a documented source-backed failure mode: the new version of seleniumbase doesnt fully load chromium and crashes whenever i run my python code
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4391

## 19. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4393

## 20. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4391

## 21. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/seleniumbase/SeleniumBase

## 22. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/seleniumbase/SeleniumBase

## 23. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/seleniumbase/SeleniumBase

## 24. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/seleniumbase/SeleniumBase/issues/4396

## 25. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Add option to set the exact Chromium revision downloaded for `sbase get chromium`
- User impact: Developers may hit a documented source-backed failure mode: Add option to set the exact Chromium revision downloaded for `sbase get chromium`
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4394

## 26. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: Chromium first launch on Mac: `Do you want the application “Chromium Helper.app” to accept incoming network connections?`
- User impact: Developers may hit a documented source-backed failure mode: Chromium first launch on Mac: `Do you want the application “Chromium Helper.app” to accept incoming network connections?`
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4395

## 27. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: On Windows, `ValueError: "I/O operation on closed pipe"` during the cleanup phase of Pure CDP Mode
- User impact: Developers may hit a documented source-backed failure mode: On Windows, `ValueError: "I/O operation on closed pipe"` during the cleanup phase of Pure CDP Mode
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4400

## 28. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: On Windows, `solve_captcha()` isn't dragging the DataDome slider enough to the right
- User impact: Developers may hit a documented source-backed failure mode: On Windows, `solve_captcha()` isn't dragging the DataDome slider enough to the right
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4399

## 29. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: SeleniumBase Recorder App 2.0
- User impact: Developers may hit a documented source-backed failure mode: SeleniumBase Recorder App 2.0
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4403

## 30. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: `get_title()` sometimes errors with `TypeError` if the page hasn't loaded enough
- User impact: Developers may hit a documented source-backed failure mode: `get_title()` sometimes errors with `TypeError` if the page hasn't loaded enough
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4401

## 31. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: High-Level Stealthy Architecture Overview
- User impact: Developers may hit a documented source-backed failure mode: High-Level Stealthy Architecture Overview
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4247

## 32. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: Maintainer away for 4 days. Hold questions until June 23, 2026
- User impact: Developers may hit a documented source-backed failure mode: Maintainer away for 4 days. Hold questions until June 23, 2026
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4406

## 33. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: slider captcha not yet passed
- User impact: Developers may hit a documented source-backed failure mode: slider captcha not yet passed
- Evidence: failure_mode_cluster:github_issue | https://github.com/seleniumbase/SeleniumBase/issues/4398

## 34. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/seleniumbase/SeleniumBase

## 35. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/seleniumbase/SeleniumBase

<!-- canonical_name: seleniumbase/SeleniumBase; human_manual_source: deepwiki_human_wiki -->