Customizing Test Runs

SeleniumBase for Rust can be configured through the BrowserConfig builder, a global config file, environment variables, or CLI flags. This guide explains the full hierarchy and shows how to make each source of configuration work for your workflow.

BrowserConfig builder#

The most direct way to configure a run is the BrowserConfig builder. Every method returns Self, so calls can be chained fluently. BrowserConfig::default() is headless, reads no environment variables, and starts a chromedriver for you when none is running at the default WebDriver URL.

use seleniumbase_rs::{BaseCase, BrowserConfig, DriverMode};#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> {    let config = BrowserConfig::default()        .with_mode(DriverMode::Uc)        .with_headless(true)        .with_mobile(true)        .with_locale("en-US")        .with_proxy("http://proxy.example.com:8080");    let mut sb = BaseCase::new(config).await?;    sb.set_timeout(15).await?;    sb.open("https://seleniumbase.io").await?;    sb.quit().await?;    Ok(())}

Key builder methods:

with_remote_webdriver_timeout(Duration) sets the client-side timeout of each request to a Remote WebDriver server (a part of a second rounds up to a whole second), the field remote_webdriver_timeout_seconds.

Blocking ads#

ad_block makes a Chromium WebDriver session (Chrome, Chromium, Edge, Brave, Comet, Opera, Chrome for Testing, chrome-headless-shell) refuse every request to a listed advertising or tracking host and its subdomains. Once the session is connected it sends the hosts to the browser with Network.setBlockedURLs through chromedriver’s DevTools channel. The list is the built-in AdBlockList::builtin(), or your own:

use seleniumbase_rs::config::ad_block_list::AdBlockList;use seleniumbase_rs::BrowserConfig;let list = AdBlockList::from_hosts(["ads.example.com", "tracker.example.net"])?;let config = BrowserConfig::default().with_ad_block_list(list);# Ok::<(), seleniumbase_rs::SeleniumBaseError>(())

A list of your own replaces the built-in one. A list that needs more than 2,000 URL patterns is refused when the session starts. Limits:

Launch settings#

The Python SeleniumBase options that shape how a browser or its driver starts live in BrowserConfig::launch (a LaunchSettings) and have builder methods of their own. Each value type reads the text the Python command line takes, so "1280,720".parse::<WindowSize>() and "eager".parse::<PageLoadStrategy>() work.

with_browser also takes Brave, Comet, Opera, Safari, InternetExplorer, ChromeForTesting and ChromeHeadlessShell (the Python --brave, --comet, --opera, --safari, --ie, --cft and --chs). Chrome for Testing and chrome-headless-shell are downloaded into downloaded_drivers/ when missing; Opera, Safari and Internet Explorer need their own driver (operadriver, safaridriver, IEDriverServer) on the PATH.

Ending a test with ESC#

with_esc_end(true) lets the person watching a headed run stop the test: BaseCase puts a key listener in the page, and the first open, click, click_link_text, highlight, wait_for_element_visible, wait_for_ready_state_complete, type_text, update_text or press_keys after ESC was pressed returns SeleniumBaseError::Skipped instead of doing its work. run_browser_test counts that as a skipped test, not a failure. A new page loses the listener, so open, refresh, go_back, go_forward, click, click_link_text and wait_for_ready_state_complete put it back. The listener is added with addEventListener, so the page keeps its own key handlers. Only the WebDriver engine (BaseCase) has the option.

Sharing a browser between tests#

with_reuse_session(true) (--reuse-session, --reuse_session, --rs, SB_REUSE_SESSION) keeps a browser open from one test to the next, as Python’s option does. BaseCase::new attaches to a browser that an earlier test of the same process started with the same configuration (everything but the start page) and has given back, and BaseCase::quit, run_browser_test or dropping the case gives it back open instead of closing it:

use seleniumbase_rs::{run_browser_test, BrowserConfig};#[tokio::test]async fn login_page_loads() -> seleniumbase_rs::Result<()> {    let config = BrowserConfig::default().with_reuse_session(true);    run_browser_test(config, async |sb| sb.open("https://example.com/login").await)    .await}

Each #[tokio::test] has its own Tokio runtime, so what is shared is the browser’s WebDriver session, not a client: a process-wide registry keeps the address of its WebDriver server, its session id and the chromedriver this crate started, and each test attaches with a client of its own.

• Before a test gets a browser back it is cleaned: an open dialog is dismissed, every window but the first is closed, every cookie is deleted (through DevTools on a Chromium browser), the open page’s local and session storage is cleared, and it goes to about:blank (then to the start page, if there is one). Python keeps the cookies and the page unless --crumbs is given; here a browser is always cleaned, because Rust tests run in any order and side by side.
• One test holds a browser at a time. A test that starts while every matching browser is held gets a browser of its own, kept for reuse too, so a run with four test threads ends up with up to four browsers. A browser that no longer answers is closed and replaced.
• get_new_driver browsers are never shared.
• BaseCase::session_id() tells which browser a test has.

with_reuse_module_session(true) (--rcs, --reuse-class-session, SB_REUSE_CLASS_SESSION) shares a browser only among the tests of one Rust module, which plays the part of Python’s test class. The module is read from the name libtest gives the thread a test runs on: login::tests::valid_password is in login::tests, and every test at the root of an integration test file is in the root module. with_reuse_class_session("Login") shares one among the tests that pass the same name instead.

Idle browsers are closed, with their chromedriver, by a background thread once no test has held them for five seconds (seleniumbase_rs::browser::reuse::set_idle_timeout, or SB_REUSE_IDLE_SECS in whole seconds), by seleniumbase_rs::shutdown_reused_sessions(), and by common::shutdown::drain_cleanups, which sbrs calls before it exits. A Rust test binary has no hook that runs after its last test, and it usually exits sooner than the idle timeout. On macOS and Linux the browser of the last tests still ends with the binary: every chromedriver and browser this crate starts belongs to a process group that a small watcher ends when the program that started it exits, also when that program is killed.

Under cargo-nextest each test is a process of its own, so nothing is shared.

Global config file#

Create sbase_config.toml in the directory you run from, for shared defaults:

browser = "chrome"headless = falsemobile = falselocale = "en-US"timeout_seconds = 10screenshot_dir = "screenshots"proxy = "http://proxy.example.com:8080"

{ "browser": "chrome", "headless": false, "timeout_seconds": 10 }

Every key is optional and any key you leave out keeps its default. The keys are the fields of Settings: browser, headless, timeout_seconds, screenshot_dir, proxy, proxy_pac_url, window_width, window_height, user_data_dir, extension_dir, locale, user_agent, mode (webdriver, cdp or uc), ad_block, reuse_session, reuse_class_session, mobile, threads, esc_end, rec_sb_cdp, remote_webdriver_timeout_seconds, webdriver_url and chrome_bin. Note that timeout_seconds is a whole number of seconds. A browser or mode that is not a known name, or a window_width without a window_height, is an error when the file is read.

Settings::load_global() looks for these names, in this order, in the current working directory only (it does not search parent directories): sbase_config.toml, .sbase_config.toml, .sbase_config. A file whose name ends in .toml is read as TOML; any other name, including .sbase_config, is read as JSON (the second tab above).

To build a BrowserConfig from the file in your own test:

use seleniumbase_rs::config::settings::Settings;use seleniumbase_rs::BaseCase;# async fn demo() -> Result<(), Box<dyn std::error::Error>> {// The global config file (if any), with the SB_* variables applied on top.// `Settings::load_from(path)` reads a file you name instead.let settings = Settings::load()?;let config = settings.to_browser_config();// `timeout_seconds` from the file or `SB_TIMEOUT` is already its default wait.let mut sb = BaseCase::new(config).await?;# sb.quit().await?;# Ok(())# }

to_browser_config() takes the WebDriver URL and the browser binary from webdriver_url and chrome_bin (SB_WEBDRIVER_URL and SB_CHROME_BIN), and does not set a fingerprint or extra arguments; add those with the builder methods afterwards.

Environment variables#

Environment variables override file values. The prefix is SB_ (not SBASE_):

export SB_HEADLESS=trueexport SB_LOCALE=fr-FRexport SB_BROWSER=chromeexport SB_TIMEOUT=20

Settings::load and Settings::from_env read exactly these, each mapped to the field of the same name: SB_BROWSER, SB_HEADLESS, SB_TIMEOUT, SB_REMOTE_WEBDRIVER_TIMEOUT, SB_SCREENSHOT_DIR, SB_PROXY, SB_PROXY_PAC_URL, SB_WINDOW_WIDTH, SB_WINDOW_HEIGHT, SB_USER_DATA_DIR, SB_EXTENSION_DIR, SB_LOCALE, SB_USER_AGENT, SB_MODE, SB_AD_BLOCK, SB_REUSE_SESSION, SB_REUSE_CLASS_SESSION, SB_MOBILE, SB_THREADS, SB_ESC_END, SB_REC_SB_CDP, SB_WEBDRIVER_URL and SB_CHROME_BIN. Booleans accept true/false, 1/0, yes/no and on/off. There is no automatic name mapping: a variable that is not in this list, such as SB_LOGGING__LOG_LEVEL, does nothing. See Settings and Global Configuration for the table, including the separate runtime variables (SB_LOG_LEVEL, SB_LOG_FORMAT, …), which RuntimeConfig::from_env() reads, and BrowserConfig::from_env(), which reads only SB_WEBDRIVER_URL and SB_CHROME_BIN:

export SB_WEBDRIVER_URL=http://localhost:4444/wd/hub

The sbrs binary reads the settings variables above when it drives a browser (sbrs open, smoke and the other browser commands). A bad value, such as SB_HEADLESS=maybe, stops the command with an error before any browser starts.

CLI flags#

cargo run --bin sbrs -- --headless --proxy http://proxy.example.com:8080 open https://seleniumbase.io

Common flags:

Run sbrs --help and sbrs <subcommand> --help for the full list of flags.

Running tests with sbrs test#

sbrs test runs cargo test (or one example) and carries the global options into the tests as SB_* environment variables, so a test that loads Settings sees them:

# Sets SB_HEADLESS=true and SB_BROWSER=firefox, and runs 2 tests at a time.cargo run --bin sbrs -- --headless --browser firefox -n 2 testcargo run --bin sbrs -- test login --test checkout --release --features turso

It accepts a name filter, --test NAME (one file from tests/), --example NAME, --release, --features a,b, and harness arguments after --. Only the options you actually pass become variables, so everything else still comes from your config file and environment. A non-default --webdriver URL reaches the tests as SB_WEBDRIVER_URL.

Combining config sources#

For a test that builds its configuration with Settings::load and then adjusts it, later sources win:

1. Built-in defaults (Settings::default()).
2. Global config file (sbase_config.toml, .sbase_config.toml or .sbase_config).
3. Environment variables (SB_*).
4. Programmatic changes, such as BrowserConfig builder calls.

sbrs test adds the command-line flags as step 3 for its tests. The sbrs binary follows the same order when it drives a browser directly (sbrs open and the like): it starts from the config file (the global one, or the one named by --config), applies the SB_* variables on top, and then the CLI flags override both. So SB_HEADLESS=true sbrs open URL runs headless, and SB_HEADLESS=true sbrs --headed open URL shows the window.

Troubleshooting#

Next steps#