Settings and Global Configuration

seleniumbase-rs supports multiple configuration layers: built-in defaults, a global config file, SB_* environment variables, and programmatic BrowserConfig overrides. This makes it easy to keep environment-specific settings out of source code while still allowing per-test customization.

This page explains the configuration hierarchy, the available settings, and how to load and combine them.

Configuration hierarchy#

Settings are resolved from lowest to highest priority. A higher-priority source overrides a lower-priority one:

1. Built-in defaults.
2. Global config file (sbase_config.toml, .sbase_config.toml, or .sbase_config).
3. Environment variables (SB_*).
4. Programmatic BrowserConfig.
5. CLI flags (when using sbrs).

Global config file#

Create sbase_config.toml in your project root (or a .sbase_config file in JSON; a flat KEY=VALUE file is not supported):

browser = "chrome"headless = falsetimeout_seconds = 30window_width = 1920window_height = 1080proxy = "http://proxy.example.com:8080"proxy_pac_url = ""mode = "webdriver"reuse_session = falsereuse_class_session = falsemobile = falsethreads = 2locale = "en-US"user_agent = ""user_data_dir = ""extension_dir = ""ad_block = falseesc_end = falserec_sb_cdp = false

{ "headless": false, "locale": "en-US", "timeout_seconds": 10 }

The file is optional. If it is missing, built-in defaults are used. The Settings::load_global() function searches for sbase_config.toml, then .sbase_config.toml, then .sbase_config in the current directory.

Loading settings programmatically#

use seleniumbase_rs::config::settings::Settings;fn main() -> Result<(), Box<dyn std::error::Error>> {    // Load the global config file (if present) and apply SB_* env overrides.    let settings = Settings::load()?;    // Or load a specific file, with the SB_* overrides on top.    let settings = Settings::load_from("staging.toml")?;    // Or only the file, leaving the environment out.    let settings = Settings::from_file("staging.toml")?;    // Convert to BrowserConfig.    let config = settings.to_browser_config();    Ok(())}

Settings::load() reads the global config file and Settings::load_from(path) reads the file you name; both apply the environment variables on top. Settings::from_file reads the file alone. All three refuse a browser or mode that is not a known name (SB_BROWSER=chrom is an error, not Chrome), and a window_width without a window_height.

Environment variables#

Every setting in Settings can be overridden with an SB_ prefixed variable:

Boolean values accept true/false, 1/0, yes/no, or on/off.

Example:

export SB_BROWSER=firefoxexport SB_HEADLESS=trueexport SB_TIMEOUT=60export SB_PROXY=http://proxy:8080export SB_THREADS=4

Runtime environment variables#

In addition to Settings, the crate reads SB_* runtime configuration for library behavior:

Remote WebDriver timeout#

When tests run against a Selenium Grid, a node that dies mid-session can leave a command waiting forever, because the WebDriver client has no reason to give up on a connection that never closes. remote_webdriver_timeout_seconds (or the SB_REMOTE_WEBDRIVER_TIMEOUT variable) puts a client-side limit on each HTTP request sent to the server.

It is unset by default, matching SeleniumBase’s REMOTE_WEBDRIVER_TIMEOUT, so the client keeps its own default until you opt in.

remote_webdriver_timeout_seconds = 600

export SB_REMOTE_WEBDRIVER_TIMEOUT=600

BrowserConfig in code#

For per-test overrides, build a BrowserConfig directly:

use seleniumbase_rs::{BrowserConfig, DriverMode};let config = BrowserConfig::default()    .with_mode(DriverMode::Uc)    .with_headless(true)    .with_proxy("http://proxy:8080")    .with_locale("en-US")    .with_extra_args(vec!["--disable-blink-features=AutomationControlled".into()]);

BrowserConfig also supports from_env() to load runtime variables directly:

use seleniumbase_rs::BrowserConfig;let config = BrowserConfig::from_env()?;

Proxy lists and ad-block lists#

Two small types in seleniumbase_rs::config hold lists that are too long for a config file field.

ProxyList is Python’s PROXY_LIST: proxies, optionally named, read from a text file (see CLI usage for the format). Each entry is validated when it is read. It resolves a name or a literal proxy (resolve), and hands proxies out in turn (next_round_robin) or at random (random); the turn counter is atomic, so one list can serve parallel tests:

use seleniumbase_rs::config::proxy_list::ProxyList;use seleniumbase_rs::BrowserConfig;let proxies = ProxyList::from_file("proxies.txt")?;let entry = proxies.next_round_robin().expect("a non-empty list");let config = BrowserConfig::default().with_proxy(entry.spec());

ProxyEntry’s Debug and Display never show a password; only spec() does.

AdBlockList is a set of hosts to refuse, with their subdomains. AdBlockList::builtin() is the crate’s starter list of advertising and tracking hosts, AdBlockList::parse reads the host rules of a hosts file or an Adblock Plus list (and counts the rules it cannot express), and url_patterns() gives the patterns for the DevTools command Network.setBlockedURLs. is_blocked(url) matches on the parsed host, so a blocked name inside a query string does not block the page.

A Chromium WebDriver session sends such a list to the browser when BrowserConfig::ad_block is on: the built-in list, or yours through with_ad_block_list(list), which replaces it. bounded_url_patterns() is what is sent. It leaves out a host whose parent domain is also listed and refuses a list that needs more than 2,000 patterns, so the browser is never given half of what you asked for. See Blocking ads.

Best practices#

• Commit a sample config file (e.g., sbase_config.example.toml) to the repo so new contributors know what settings exist.
• Keep secrets (passwords, API keys) out of config files; use environment variables or a secrets manager.
• Use Settings::load_global() in test harnesses and BrowserConfig overrides for individual tests.
• Use BrowserConfig::from_env() in deployable applications so operators can change behavior without rebuilding.

Configuration checklist#

• A sample config file is committed to the repository.
• Secrets are loaded from environment variables.
• Per-test overrides use BrowserConfig builders.
• CI uses environment variables or a dedicated config file.
• SB_* variables are documented for operators.

Related reading#