Writing Browser Tests

seleniumbase-rs does not ship its own test runner. Instead, it integrates with standard Rust tooling: #[tokio::test], cargo test, cargo nextest run, and the run_browser_test lifecycle helper. This keeps tests idiomatic and lets you use the full Rust testing ecosystem.

This page maps common testing concepts from Python and JavaScript to Rust, shows the recommended test shape, and explains how to organize a growing suite.

Concept mapping#

Recommended test shape#

Use run_browser_test to guarantee cleanup. It creates a BaseCase, runs your async test body, and then calls quit even when the body fails:

use seleniumbase_rs::{run_browser_test, BrowserConfig, Result};#[tokio::test]async fn user_can_open_the_home_page() -> Result<()> {    run_browser_test(BrowserConfig::default(), async |sb| {        sb.open("https://example.com").await?;        sb.assert_element("h1").await?;        sb.assert_text("Example Domain", "h1").await    })    .await}

The test is an async closure, async |sb| { .. } (or an async fn that takes &mut BaseCase). It receives &mut BaseCase and returns Result<()>, that is Result<(), SeleniumBaseError>, so ? converts any error with a From impl into it. The browser is closed when the test panics too, and the panic is then raised again. Code written for older versions used |sb| Box::pin(async move { .. }); drop the Box::pin and write async |sb| { .. }. To test a page with the Pure CDP engine instead, use run_cdp_test(LaunchOptions::default(), async |page| { .. }).

Run the test:

cargo test user_can_open_the_home_page

Running the full suite#

For small suites, the default test runner is fine. For larger suites, install and use cargo-nextest:

cargo test

cargo install cargo-nextestcargo nextest run

Sharing helpers#

As your suite grows, extract reusable helpers into modules or crates:

// tests/helpers/mod.rsuse seleniumbase_rs::{BaseCase, Result};pub async fn login(sb: &mut BaseCase, user: &str, pass: &str) -> Result<()> {    sb.open("https://example.com/login").await?;    sb.type_text("#username", user).await?;    sb.type_text("#password", pass).await?;    sb.click("#submit").await?;    sb.assert_element_visible("#dashboard").await}

use seleniumbase_rs::ElementApi;async fn fill_email<E: ElementApi>(sb: &mut E, email: &str) -> Result<(), seleniumbase_rs::SeleniumBaseError> {    sb.type_text("#email", email).await}

Parameterized tests#

Rust does not have built-in parameterized tests, but you can achieve the same result with a loop inside a single test or with a parameterized-test crate:

#[tokio::test]async fn login_with_multiple_users() -> Result<()> {    let users = [("alice", "secret1"), ("bob", "secret2")];    for (user, pass) in users {        run_browser_test(BrowserConfig::default(), async |sb| {            sb.open("https://example.com/login").await?;            sb.type_text("#username", user).await?;            sb.type_text("#password", pass).await?;            sb.click("#submit").await?;            sb.assert_element_visible("#dashboard").await        })        .await?;    }    Ok(())}

Test organization#

A typical project layout looks like this:

Integration tests in tests/ are compiled as separate binaries, which gives each test its own browser process and reduces shared-state bugs.

Configuration per test#

For tests that need special configuration, build a BrowserConfig directly:

use seleniumbase_rs::{BrowserConfig, DriverMode, run_browser_test, Result};#[tokio::test]async fn uc_smoke_test() -> Result<()> {    let config = BrowserConfig::default()        .with_mode(DriverMode::Uc)        .with_headless(true);    run_browser_test(config, async |sb| {        sb.open("https://example.com").await?;        sb.assert_title_contains("Example").await    })    .await}

For global defaults, use sbase_config.toml or SB_* environment variables. See Settings and Configuration for details.

Macros for shorter tests#

The sb_test! macro generates a #[tokio::test] wrapper and the run_browser_test boilerplate:

use seleniumbase_rs::{sb_test, BrowserConfig};sb_test!(home_page_loads, BrowserConfig::default(), |sb| {    sb.open("https://example.com").await?;    sb.assert_text("Example Domain", "h1").await});

This expands to the same shape as the manual example above. It is optional but useful for linear tests where the reduced noise improves readability.

See Macros for the full macro catalog.

Common pitfalls#

Testing checklist#

• Tests use run_browser_test or sb_test! for automatic cleanup.
• Helpers are extracted into tests/helpers/ or a shared crate.
• Configuration is externalized for environment differences.
• The suite is run with cargo test or cargo nextest run.
• Tests capture screenshots or page source on failure.