# seleniumbase/seleniumbase architecture

> Architecture diagram of the GitHub repository seleniumbase/seleniumbase, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/seleniumbase/seleniumbase
- Repository: https://github.com/seleniumbase/seleniumbase

## Overview

##### Project Type & Purpose
- SeleniumBase is an open‑source Python framework/library for browser automation and end‑to‑end testing.
- It provides both:
- A command‑line interface (CLI) (“seleniumbase” and “sbase” console scripts)
- A Python API (modules under seleniumbase/ and sbase/)
- Key use cases: writing tests (pytest, behave, raw Python), recording tests, generating reports, integrating with CI/CD, driving Selenium WebDriver or CDP.

##### Top‑Level Components
- CLI Layer
- Entry‑point scripts (seleniumbase/__main__.py, sbase/__main__.py)
- console_scripts adapters under seleniumbase/console_scripts/
- Core Library
- seleniumbase/core/ – application manager, browser launcher, driver & session helpers, CDP support
- seleniumbase/fixtures/ – BaseCase, page actions, assertions, deferred asserts
- seleniumbase/common/ – decorators, encryption, exceptions, obfuscation
- seleniumbase/config/ – default settings, proxy and ad‑block lists
- seleniumbase/js_code/ – in‑browser JS snippets (recording, live updates)
- seleniumbase/plugins/ – pytest and other plugins (test discovery, reporting, dashboard)
- seleniumbase/undetected/ – undetected‑chromedriver wrapper and CDP driver layer
- seleniumbase/utilities/selenium_grid/ – hub/node scripts for distributed testing
- seleniumbase/translate/ – multi‑language support
- seleniumbase/extensions/ – bundled browser extensions (ad‑block, CSP bypass)
- sbase Package
- A thin wrapper that mirrors key functionality in seleniumbase/ for “sbase” CLI
- Examples & Documentation
- examples/ – >200 test and demo scripts in pytest, raw Python, behave BDD, CDP mode, chart maker, recorder
- help_docs/ – markdown guides for features, options, integrations
- integrations/ – sample CI/CD, Docker, cloud, Grid, Katalon, Node.js, GitHub Actions
- Build & Deployment
- setup.py, pyproject.toml, requirements.txt, Dockerfile
- CI definitions (.github/workflows, azure-pipelines.yml)

##### Component Relationships & Data Flow
- User invokes CLI script (seleniumbase or sbase) or imports BaseCase/SB/Driver in Python.
- CLI parses arguments via console_scripts helpers → loads config settings → calls core.application_manager or driver_manager.
- Core launches browser driver (via seleniumbase/core/browser_launcher or undetected/chromedriver) → establishes WebDriver/CDP session.
- Fixtures/base_case orchestrate test lifecycle: setup, action methods (open(), click(), type()), assertions, teardown.
- Plugins intercept test events (pytest_plugin) to collect logs, screenshots, build dashboard, send to MySQL/S3 if configured.
- Utilities/selenium_grid enable parallel distribution: grid_hub and grid_node processes communicate over HTTP.
- Integrations/ samples show how CLI + Python API can be wired into CI pipelines or Docker containers.
- Examples import SB or BaseCase → exercise core modules → generate reports in latest_logs/ or dashboard.html.

##### Architectural Patterns & Design Principles
- Layered Architecture
- Presentation: CLI console_scripts
- Application: core & fixtures (Facade over Selenium WebDriver)
- Infrastructure: drivers, undetected, plugins, utilities
- Persistence: optional MySQL, S3 via core/s3_manager & plugins/db_reporting_plugin
- Plugin Architecture
- Pytest plugins (seleniumbase/plugins/pytest_plugin.py) for extending test runner behavior
- Facade Pattern
- BaseCase, SB, Driver classes unify complex Selenium/WebDriver interactions into simple methods
- Strategy Pattern
- Multiple driver strategies: standard WebDriver, undetected‑chromedriver (CDP), remote Grid
- Dependency Injection via CLI options & settings files

- Be exhaustive: include at least one entity for each major directory (seleniumbase/core, fixtures, plugins, undetected, utilities, console_scripts, integrators).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: User & Examples
    User["User / Test Scripts"] 
    Examples["examples/"]:::external
    User --> Examples
    click Examples "https://github.com/seleniumbase/seleniumbase/tree/master/examples/"

    %% CLI & API Layer
    subgraph "CLI & API Layer"
        direction TB
        SB_CLI["seleniumbase/__main__.py"]:::cli_api
        SBASE_CLI["sbase/__main__.py"]:::cli_api
        CScripts["seleniumbase/console_scripts/"]:::cli_api
    end
    User --> SB_CLI
    User --> SBASE_CLI
    SB_CLI --> CScripts
    SBASE_CLI --> CScripts
    click SB_CLI "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/__main__.py"
    click SBASE_CLI "https://github.com/seleniumbase/seleniumbase/blob/master/sbase/__main__.py"
    click CScripts "https://github.com/seleniumbase/seleniumbase/tree/master/seleniumbase/console_scripts/"

    %% Core Library Layer
    subgraph "Core Library" 
        direction TB
        AppMgr["application_manager.py"]:::core
        BrowserLauncher["browser_launcher.py"]:::core
        SB_Driver["sb_driver.py"]:::core
        SessionHelper["session_helper.py"]:::core
        SettingsParser["settings_parser.py"]:::core
        ReportHelper["report_helper.py"]:::core
        S3Manager["s3_manager.py"]:::core
        MySQLHelper["mysql.py"]:::core
    end
    CScripts --> AppMgr
    AppMgr --> BrowserLauncher
    click AppMgr "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/core/application_manager.py"
    click BrowserLauncher "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/core/browser_launcher.py"
    click SB_Driver "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/core/sb_driver.py"
    click SessionHelper "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/core/session_helper.py"
    click SettingsParser "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/core/settings_parser.py"
    click ReportHelper "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/core/report_helper.py"
    click S3Manager "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/core/s3_manager.py"
    click MySQLHelper "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/core/mysql.py"

    %% Fixtures & Facade
    subgraph "Fixtures (Facade & Page Actions)"
        direction TB
        BaseCase["base_case.py"]:::core
        PageActions["page_actions.py"]:::core
    end
    AppMgr --> BaseCase
    BaseCase --> PageActions
    click BaseCase "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/fixtures/base_case.py"
    click PageActions "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/fixtures/page_actions.py"

    %% Common Utilities
    subgraph "Common Utilities"
        direction TB
        Decorators["decorators.py"]:::core
        Encryption["encryption.py"]:::core
        Exceptions["exceptions.py"]:::core
    end
    BaseCase --> Decorators
    BaseCase --> Encryption
    BaseCase --> Exceptions
    click Decorators "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/common/decorators.py"
    click Encryption "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/common/encryption.py"
    click Exceptions "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/common/exceptions.py"

    %% Configuration
    subgraph Configuration
        direction TB
        Settings["settings.py"]:::core
        ProxyList["proxy_list.py"]:::core
        AdBlockList["ad_block_list.py"]:::core
    end
    AppMgr --> Settings
    AppMgr --> ProxyList
    AppMgr --> AdBlockList
    click Settings "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/config/settings.py"
    click ProxyList "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/config/proxy_list.py"
    click AdBlockList "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/config/ad_block_list.py"

    %% JS Code
    subgraph "In-Browser JS Snippets"
        direction TB
        RecorderJS["recorder_js.py"]:::core
        LiveJS["live_js.py"]:::core
        ActiveCSS["active_css_js.py"]:::core
    end
    BaseCase --> RecorderJS
    BaseCase --> LiveJS
    click RecorderJS "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/js_code/recorder_js.py"
    click LiveJS "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/js_code/live_js.py"
    click ActiveCSS "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/js_code/active_css_js.py"

    %% Plugins & Extensions
    subgraph "Plugins & Utilities"
        direction TB
        PytestPlugin["pytest_plugin.py"]:::plugin
        DBReporting["db_reporting_plugin.py"]:::plugin
        S3Logging["s3_logging_plugin.py"]:::plugin
        SeleniumPlugin["selenium_plugin.py"]:::plugin
        Screenshots["screen_shots.py"]:::plugin
        Extensions["extensions/"]:::plugin
        Translate["translate/"]:::core
        Undetected["undetected/"]:::core
        GridUtils["utilities/selenium_grid/"]:::plugin
    end
    BaseCase --> PytestPlugin
    AppMgr --> DBReporting
    AppMgr --> S3Logging
    AppMgr --> SeleniumPlugin
    BaseCase --> Screenshots
    AppMgr --> Extensions
    AppMgr --> Translate
    BrowserLauncher --> Undetected
    AppMgr --> GridUtils
    click PytestPlugin "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/plugins/pytest_plugin.py"
    click DBReporting "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/plugins/db_reporting_plugin.py"
    click S3Logging "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/plugins/s3_logging_plugin.py"
    click SeleniumPlugin "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/plugins/selenium_plugin.py"
    click Screenshots "https://github.com/seleniumbase/seleniumbase/blob/master/seleniumbase/plugins/screen_shots.py"
    click Extensions "https://github.com/seleniumbase/seleniumbase/tree/master/seleniumbase/extensions/"
    click Translate "https://github.com/seleniumbase/seleniumbase/tree/master/seleniumbase/translate/"
    click Undetected "https://github.com/seleniumbase/seleniumbase/tree/master/seleniumbase/undetected/"
    click GridUtils "https://github.com/seleniumbase/seleniumbase/tree/master/seleniumbase/utilities/selenium_grid/"

    %% External Dependencies
    subgraph "External Services"
        direction TB
        WebDriver["WebDriver/CDP"]:::external
        Browser["Browser"]:::external
        MySQLDB["MySQL Database"]:::external
        S3Bucket["S3 Storage"]:::external
        GridHub["Grid Hub"]:::external
        GridNode["Grid Node"]:::external
        CI["CI/CD Services"]:::external
    end
    BrowserLauncher --> WebDriver
    WebDriver --> Browser
    ReportHelper --> MySQLDB
    S3Manager --> S3Bucket
    GridUtils --> GridHub
    GridUtils --> GridNode
    User --> CI

    %% Flow connections
    BaseCase --> WebDriver
    PytestPlugin --> AppMgr

    %% Styles
    classDef cli_api fill:#ADD8E6,stroke:#000;
    classDef core fill:#90EE90,stroke:#000;
    classDef plugin fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
