The Problem

Teams that need reliable browser‑automation for testing, scraping or bypassing bot‑detection often stitch together Selenium, custom drivers and ad‑hoc scripts. That results in duplicated code, fragile imports and unclear build reproducibility.

What This Does

The repository is a portfolio of five self‑contained projects:

  • seleniumbase/ – the core library (≈131 Python modules) that implements the SeleniumBase API, CDP driver, and “undetected” stealth helpers. Entry points live in seleniumbase/__main__.py and the CLI script seleniumbase/console_scripts/run.py.
  • examples/ – >400 files showing ready‑to‑run test cases, BDD features, page‑object scaffolds and migration guides.
  • integrations/ – small adapters for Brython, Node.js and Behave; the Node server (integrations/node_js/server.js) demonstrates a runtime‑eval pattern.
  • sbase/ – a thin wrapper exposing a __main__ that forwards to the core CLI.
  • mkdocs_build/ – documentation build assets (only one Python file).

The core package supplies high‑level helpers such as click(), type(), assert_text(), and a CDP‑based stealth mode (seleniumbase/undetected/cdp_driver/). Translation modules (seleniumbase/translate/*.py) expose the same API in dozens of languages.

How It Is Wired

Execution begins in seleniumbase/console_scripts/run.py:980 (main). The static call graph shows main reaches 388 functions across the repo, invoking the most fan‑in utilities:

  • sleep – 187 call sites
  • click – 128 call sites
  • execute_script – 83 call sites
  • assert_text – 79 call sites

main immediately performs filesystem I/O (open via self.sb.open) and later spawns a WebSocket listener (run -> listener_loop) that receives network data (self.connection.websocket.recv). The path main → open writes logs, while run → listener_loop → websocket.recv touches the network.

The hub module seleniumbase/__init__.py is imported by 378 other modules, making it a high‑impact change surface. It participates in a documented import cycle (12 modules, e.g., seleniumbase/undetected/cdp_driver/connection.py) that raises the instability metric to 0.02 for the hub and 0.88‑0.89 for several CDP driver files. Circular imports increase the risk of subtle runtime errors and hamper refactoring.

The most complex source files (seleniumbase/translate/master_dict.py, seleniumbase/behave/behave_sb.py, seleniumbase/console_scripts/run.py) exceed 2 300 lines, contributing to a high cognitive load. Deeply nested functions (max depth 10) appear in the CDP driver (connection.py, tab.py, config.py).

External effects are limited to:

  • Filesystem writes (log files, temporary driver binaries) – 206 functions.
  • Network calls (WebSocket for CDP) – 18 functions.
  • Minimal database or cryptographic usage (3 functions each).

No other outbound services are referenced, and the repository does not expose a persistent server beyond the optional Node.js integration.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/SeleniumBase
cd SeleniumBase

# Install Python dependencies (pip reads pyproject.toml / requirements.txt)
python -m pip install -r requirements.txt

# Optional: build the Docker image (Dockerfile present)
docker build -t seleniumbase:dev .

# Run the core CLI (example: open a page and take a screenshot)
python -m seleniumbase.console_scripts.run \
    --browser=chrome \
    --headless \
    "https://example.com" \
    --save-screenshot=example.png

For the Node integration:

cd integrations/node_js
npm install          # package.json defines dependencies
node server.js       # starts the example server (contains eval)

The examples/ directory contains runnable scripts (examples/basic_test.py) that can be executed with pytest or via the CLI entry point.

Real‑World Use

A QA team can embed SeleniumBase in their CI pipeline to run end‑to‑end UI tests:

from seleniumbase import BaseCase

class LoginTest(BaseCase):
    def test_login(self):
        self.open("https://app.example.com")
        self.type("#username", "alice")
        self.type("#password", "s3cr3t")
        self.click("button.submit")
        self.assert_text("Welcome, Alice", "h1")

Running pytest examples/boilerplates/sb_fixture_test.py validates the flow with a single command.

Code Health & Issues

  • HIGH – No lockfile beside pyproject.toml.
  • HIGH – eval over a runtime value in integrations/node_js/server.js.
  • MEDIUM – GitHub token permissions not least‑privileged (.github/workflows/python-nightly-mac.yml).
  • MEDIUM – Dependabot/Renovate not configured.
  • MEDIUM – Docker base image not pinned by digest (Dockerfile).
  • MEDIUM – No dependency‑vulnerability scan in CI.
  • MEDIUM – Checkout step keeps credentials (persist-credentials: false missing).
  • MEDIUM – Container runs as root; no non‑root USER defined.
  • MEDIUM – Test suite covers only 2 files of 136 source files (≈1.5 % coverage).
  • LOW – Workflow jobs lack timeout-minutes.

These findings are generated by deterministic static analysis; each includes file paths and concrete evidence.

The Bottom Line

SeleniumBase delivers a feature‑rich, multilingual automation library with extensive examples, but the codebase suffers from high coupling (hub module, import cycles), oversized files and limited test coverage. It is suitable for teams that need a ready‑made framework and are prepared to invest in refactoring and adding safeguards (lockfiles, CI hardening) before using it in production.