Debugging

When a test or a command fails, the cause is usually one of three things: the page, the browser or driver, or the code. This page lists the tools the crate has for each, from turning on the logs to reproducing a failure without Chrome.

Turn on the logs#

The crate logs with tracing. Logs go to standard error, never to standard output: standard output carries what a program produces, such as an sbrs command’s answer or the protocol messages of sbrs-mcp.

sbrs and sbrs-mcp install the log subscriber themselves, with init_tracing_from_runtime. These variables control it:

SB_LOG_LEVEL=debug sbrs --headless smoke https://example.com

RUST_LOG=error,seleniumbase_rs=debug sbrs --headless smoke https://example.com

SB_LOG_FORMAT=json SB_LOG_LEVEL=debug sbrs --headless smoke https://example.com

In your own program or test#

A program, a test or an example has no subscriber until it installs one. Install it once, at the start; a second call is ignored.

use seleniumbase_rs::{init_tracing_from_runtime, RuntimeConfig};fn main() -> Result<(), seleniumbase_rs::SeleniumBaseError> {    // SB_LOG_LEVEL, else RUST_LOG, else info; SB_LOG_FORMAT picks pretty or json.    init_tracing_from_runtime(&RuntimeConfig::from_env()?);    Ok(())}

All five are at the crate root. In a test, call seleniumbase_rs::init_tracing() first, then run it with RUST_LOG=seleniumbase_rs=debug.

Errors are logged as structured events with error.category, error.transient and error.hint. Log one yourself with .log() on a SeleniumBaseError or .log_err() on a result, and add where it happened with .sb_context("while loading profile"). See Tracing and Logging.

Features for a debugging build#

RUSTFLAGS="--cfg tokio_unstable" cargo run --features tokio-console --bin sbrs -- --headless smoke https://example.com

cargo install --locked tokio-consoletokio-console

Watch the browser#

Headless is the default. To see the window, turn it off:

use seleniumbase_rs::BrowserConfig;let config = BrowserConfig::default().with_headless(false);

use seleniumbase_rs::sb_cdp::LaunchOptions;let options = LaunchOptions::builder().headless(false).build()?;

sbrs --headed open https://example.comSB_HEADLESS=false sbrs open https://example.com

On Linux without a display, run under a virtual display such as Xvfb; see Operating systems.

Slow the run down#

Demo mode outlines each element before an interactive call and pauses after it; slow mode pauses without the outline. Both go in the configuration:

use std::time::Duration;use seleniumbase_rs::{BrowserConfig, RunSettings};let config = BrowserConfig::default()    .with_headless(false)    .with_run_settings(        RunSettings::default()            .with_demo_mode(true)            .with_demo_sleep(Duration::from_millis(800)),    );

Keep a browser open to inspect#

sbrs devtools starts Chrome with the pure CDP engine and a DevTools endpoint on 127.0.0.1:9222, and keeps it running until you press Ctrl+C. Attach a DevTools client to it; see DevTools MCP servers.

Keep evidence when a test fails#

Plugins runs a test like run_browser_test and lets plugins look at the page when it fails, before the browser is closed. Two plugins come with the crate:

use seleniumbase_rs::plugins::observer::Plugins;use seleniumbase_rs::plugins::page_source::PageSourceOnFailurePlugin;use seleniumbase_rs::plugins::screen_shots::ScreenshotOnFailurePlugin;use seleniumbase_rs::{BrowserConfig, Result};#[tokio::test]async fn login_works() -> Result<()> {  let mut plugins = Plugins::new()      .with(ScreenshotOnFailurePlugin::new("latest_logs"))      .with(PageSourceOnFailurePlugin::new("latest_logs"));  plugins      .run_browser_test("login_works", BrowserConfig::default(), async |sb| {          sb.open("https://example.com").await?;          sb.assert_title("Example Domain").await      })      .await}

• On a failure they save login_works_<date>_<time>.png and .html in the folder you name. An existing file is never replaced.
• A plugin that fails (a full disk, a browser that has gone) is logged and does not change the test’s result. A test that panics is a failure for the plugins too, and the panic is raised again afterwards.
• For the pure CDP engine, plugins.run_cdp_test(name, launch_options, async |page| ...) does the same with a Page.

To save evidence by hand: save_screenshot("login.png") and save_page_source("login.html") write into the logs folder, latest_logs. The name must be a bare file name; one with a directory part or .. is refused. js_errors() on a pure CDP Page lists the page’s uncaught script errors, and assert_no_js_errors() fails on the first, on either engine.

Reproduce without Chrome#

Browser::new_mocked() returns a pure CDP browser that never launches Chrome. Every protocol command it receives is recorded and answered by the handler you register. It has one blank tab, and every navigation finishes at once. Any other command succeeds with an empty result until you say otherwise.

use seleniumbase_rs::sb_cdp::Browser;use serde_json::json;#[tokio::test]async fn reads_the_title() -> Result<(), seleniumbase_rs::SeleniumBaseError> {    let (browser, mock) = Browser::new_mocked();    mock.reply("Runtime.evaluate", json!({ "result": { "value": "Example Domain" } }));    let page = browser.default_page().await?;    assert_eq!(page.title().await?, "Example Domain");    assert!(!mock.calls_to("Runtime.evaluate").is_empty());    Ok(())}

• Run the existing mock tests with cargo test --features test-util --test sb_cdp_mock. In this repository a test file that uses the mock starts with #![cfg(feature = "test-util")].
• page.with_timeout(Duration::from_millis(150)) makes the failure paths quick.
• The crate’s own unit tests have a WebDriver counterpart, MockWebDriver in src/api/base_case_impls/base_case_impl_common.rs. It is #[cfg(test)], so only those unit tests can use it.

More in Testing without Chrome.

Record the network#

A HAR shows every request a tab made, with headers, status and timings. Start the recorder before the navigation you want to see:

let recorder = page.start_har().await?;page.goto("https://example.com").await?;let har = recorder.finish().await?;har.save("latest_logs/example.har")?;

Chrome’s and Firefox’s developer tools and HAR viewers open the file. start_har_with(HarOptions::new().content(true)) keeps the response bodies too. A HAR holds cookies, so treat it like the session it came from. See Recording a HAR.

Check the setup#

sbrs doctor prints the SB_* settings (and any it could not read), the Chrome it found, the patch cache, and the chromedriver it found with its major version next to Chrome’s. Each problem comes with a hint. An AI agent gets the same from the MCP tool diagnose_environment.

Driver problems#

The pure CDP engine needs no driver, so a failure that only happens with the WebDriver engine points at chromedriver.

Before it starts a driver, the launcher makes the file runnable (browser::driver_access::make_runnable): it sets a missing execute bit, removes the macOS quarantine flag and, after a patch on macOS, signs the binary again ad hoc. Firefox and Edge use geckodriver and msedgedriver; see Operating systems and Common problems.

The MCP server’s logs#

sbrs-mcp speaks the protocol on standard output and logs to standard error. Set the log variables in the client’s configuration; where the client shows the server’s standard error depends on the client.

{  "mcpServers": {    "seleniumbase-cdp": {      "command": "sbrs-mcp",      "args": ["--server", "cdp"],      "env": { "SB_LOG_LEVEL": "debug", "SB_MCP_OUTPUT_DIR": "/tmp/seleniumbase-output" }    }  }}

• An invalid SB_* variable is logged as a warning when the server starts, and its default is used.
• A failed tool call is answered with a report: a stable kind, the call that was tried, the page’s state, a hint and up to three next tools to try, such as get_console_messages and diagnose_environment. See When a call fails.
• From a checkout, SB_LOG_LEVEL=debug cargo run --bin sbrs-mcp -- --server cdp starts the server by hand; it reads the protocol on standard input and stops when that closes, or on Ctrl+C.

Debug one test#

cargo test --features "mcp-server test-util" --test sb_cdp_mock waiting_succeeds_once_the_element_appears -- --nocapture

cargo test --features "mcp-server test-util" --test sb_cdp_mock -- --exact waiting_succeeds_once_the_element_appears

cargo test -p seleniumbase-rs --lib tracing_util

cargo test --test sb_cdp_chrome -- --ignored --nocapture --test-threads=1

cargo test -p seleniumbase-rs-cli --test cli_e2e_chrome -- --ignored

RUST_BACKTRACE=1 cargo test --features "mcp-server test-util" --test sb_cdp_mock -- --nocapture

• The name after --test is the file in tests/ (or crates/cli/tests/, with -p seleniumbase-rs-cli). A word after it filters the tests by name.
• Tests that need a real Chrome are #[ignore]d: add --ignored, and run one binary at a time.
• --nocapture shows what the test prints as it runs. Logs appear only if the test installs a subscriber (see In your own program or test).

rust-analyzer#

Use rust-analyzer, or cargo check, for types and references before a full build. The repository’s rust-analyzer.toml:

• turns on the mcp-server and test-util features, without which src/mcp and the test helpers get no diagnostics;
• checks into a target directory of its own (targetDir = true), so analysis never waits on the lock that builds and test runs hold;
• keeps two threads and no cache priming, for a small machine that is also compiling.

Code behind other features, such as base_case_impl_gui.rs (feature gui), gets diagnostics only when you add that feature to your editor’s rust-analyzer settings.

Known traps#

Next steps#