Working with SeleniumBase for Rust

This guide walks you through your first browser automation test with seleniumbase-rs. By the end you will have a working Rust project that opens a browser, interacts with a page, asserts on the result, and cleans up.

Prerequisites#

• Rust toolchain 1.99 or newer (the crate’s rust-version).
• A Chromium-based browser such as Google Chrome, Chromium, or Microsoft Edge.
• A network connection for the first build (dependencies may need to be fetched).

Create a new project#

cargo new my_first_testcd my_first_test

[dependencies]seleniumbase-rs = { git = "https://github.com/MustCodeAl/seleniumbase-rs" }tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Write your first test#

use seleniumbase_rs::{BaseCase, BrowserConfig, DriverMode};#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> {    // 1. Configure the browser.    let config = BrowserConfig::default()        .with_mode(DriverMode::Uc)        .with_headless(false);    // 2. Create the test case. This starts the browser and driver if needed.    let mut sb = BaseCase::new(config).await?;    // 3. Automate.    sb.open("https://seleniumbase.io/simple/login").await?;    sb.type_text("#username", "demo_user").await?;    sb.type_text("#password", "secret_pass").await?;    sb.click("#log-in").await?;    // 4. Assert.    sb.assert_text_visible("Welcome!", "body").await?;    // 5. Clean up.    sb.quit().await?;    Ok(())}

cargo run

How it works#

• BrowserConfig::default() returns a default configuration pointing at http://localhost:4444 with headless mode enabled.
• with_mode(DriverMode::Uc) enables Undetected Chromedriver mode, which applies anti-detection evasions.
• with_headless(false) runs the browser with a visible window so you can watch the test. In CI you usually want true.
• BaseCase::new(config).await? creates the browser session. If no WebDriver server is running, the crate attempts to start one.
• sb.open(url).await? navigates to the requested page.
• sb.type_text(selector, text).await? finds the element, clears it, and types.
• sb.click(selector).await? clicks the element.
• sb.assert_text_visible(text, selector).await? waits up to the default timeout (sb.set_timeout(secs)) for the text to be visible and fails if it never is, as Python’s assert_text does. For a different wait, call sb.wait_for_text(text, selector, timeout_secs).await?.
• sb.quit().await? closes the browser and ends the session.

Configuration#

BrowserConfig is a plain struct with with_* builder methods. These are the settings most programs touch (all are in seleniumbase_rs::BrowserConfig):

Two constructors build the starting point. BrowserConfig::default() uses the defaults above and reads no environment variable. BrowserConfig::from_env() returns a Result and reads the SB_* variables, which suits a deployed test run because the same binary then needs no code change per environment:

A value that does not parse (a non-number, or a SB_LOG_FORMAT other than pretty or json) makes from_env return SeleniumBaseError::InvalidConfig; from_env_lenient keeps the good values and lists the bad ones.

A complete example that needs no network#

This program is the whole project: Cargo.toml from above and this src/main.rs. It loads a page from a string, types, clicks, asserts, saves a screenshot, and closes the browser even if an assertion fails (run_browser_test always calls quit).

use seleniumbase_rs::{init_tracing, run_browser_test, BrowserConfig};const PAGE: &str = r#"<!doctype html><title>Greeter</title><input id="name"><button id="go"  onclick="document.getElementById('out').textContent =           'Hello, ' + document.getElementById('name').value">Go</button><p id="out"></p>"#;#[tokio::main]async fn main() -> seleniumbase_rs::Result<()> {    init_tracing(); // install the log subscriber; RUST_LOG=debug for more    // SB_* variables from the environment, headless unless you change it.    let config = BrowserConfig::from_env()?.with_headless(true);    run_browser_test(config, async |sb| {        sb.load_html_string(PAGE).await?;        sb.type_text("#name", "Ferris").await?;        sb.click("#go").await?;        // The expected text comes first, the selector second, as in Python.        sb.assert_exact_text("Hello, Ferris", "#out").await?;        // Saved into the logs directory; the name must be a plain file name.        sb.save_screenshot("greeter.png").await.map(|_| ())    })    .await}

cargo run starts (or downloads, then starts) chromedriver, opens a headless Chrome, and exits with status 0 when every step passes. On a failed assertion the error is printed and the exit status is non-zero.

The same page without a driver#

The pure CDP engine (seleniumbase_rs::sb_cdp) talks to Chrome directly, so there is no chromedriver to download or start. It uses the same tokio dependency:

use seleniumbase_rs::sb_cdp::{Browser, LaunchOptions};#[tokio::main]async fn main() -> Result<(), seleniumbase_rs::SeleniumBaseError> {    let browser = Browser::launch(LaunchOptions::builder().headless(true).build()?).await?;    let page = browser.default_page().await?;    page.goto("seleniumbase.io/simple/login").await?; // https:// is added for you    page.locator("#username").fill("demo_user").await?;    page.locator("#password").fill("secret_pass").await?;    page.locator("button").click().await?;    page.locator("h1").expect().to_contain_text("Welcome").await?;    browser.close().await?;    Ok(())}

Page also implements the capability traits (BrowserApi, ElementApi, AssertionApi, ScreenshotApi), so a helper written over those traits runs on both engines; see Capability traits. The full engine is in Pure CDP.

Writing a #[tokio::test] instead of main#

For real test suites, use the test harness:

// tests/login.rsuse seleniumbase_rs::{run_browser_test, BrowserConfig, DriverMode, Result};#[tokio::test]async fn login_succeeds() -> Result<()> {    let config = BrowserConfig::default()        .with_mode(DriverMode::Uc)        .with_headless(false);    run_browser_test(config, async |sb| {        sb.open("https://seleniumbase.io/simple/login").await?;        sb.type_text("#username", "demo_user").await?;        sb.type_text("#password", "secret_pass").await?;        sb.click("#log-in").await?;        sb.assert_text_visible("Welcome!", "body").await    })    .await}

Run the test:

cargo test login_succeeds

Common startup errors#

Next steps#