Headless and Headed Browsers

with_headless(true) runs without a window (the default), and with_headless(false) opens one. A value you set in code is final: no variable or file changes it later.

use seleniumbase_rs::{run_browser_test, BrowserConfig, Result};#[tokio::test]async fn shows_the_title() -> Result<()> {    // `false` opens a window; `true` (the default) runs without one.    let config = BrowserConfig::default().with_headless(false);    run_browser_test(config, async |sb| {        sb.open("https://example.com").await?;        sb.assert_title("Example Domain").await    })    .await}

LaunchOptionsBuilder::headless(bool) sets the mode. Leave it unset to get the default for the system: headless on Linux, where there is usually no display, and headed elsewhere. LaunchOptions::is_headless() shows which mode the options will launch.

use seleniumbase_rs::sb_cdp::{Browser, LaunchOptions};#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> {    let options = LaunchOptions::builder().headless(true).build()?;    assert!(options.is_headless());    let browser = Browser::launch(options).await?;    let page = browser.default_page().await?;    page.goto("https://example.com").await?;    std::fs::write("example.png", page.screenshot().await?)?;    browser.close().await?;    Ok(())}

--headless and --headed are global options, so they go before the subcommand:

sbrs --headless open https://example.comsbrs --headed open https://example.comsbrs --headless --browser firefox test   # the tests see SB_HEADLESS=true

• A flag beats SB_HEADLESS, and SB_HEADLESS beats the settings file.
• If you pass both flags, --headless wins.
• These flags take no value: --headless=false is refused. Use --headed.
• A global option written after the subcommand is refused too.
• sbrs test passes the flag to the tests as SB_HEADLESS, so a test that loads Settings sees it.
• sbrs devtools also has its own --headless option, written after devtools.

SB_HEADLESS=true cargo test --test ui

SB_HEADLESS is read by Settings::load(), Settings::load_from(path), Settings::from_env() and the sbrs browser commands. It is not read by BrowserConfig::from_env(), the pure CDP engine or sbrs-mcp. To make a BaseCase follow it, build the configuration from Settings:

use seleniumbase_rs::{BrowserConfig, Result, Settings};fn config() -> Result<BrowserConfig> {    // sbase_config.toml if there is one, then the SB_* variables on top.    Ok(Settings::load()?.to_browser_config())}

For the pure CDP engine, read it yourself. The programs that sbrs import-playwright and sbrs import-puppeteer write do this:

use seleniumbase_rs::config::settings::Settings;use seleniumbase_rs::sb_cdp::LaunchOptions;fn launch_options() -> Result<LaunchOptions, seleniumbase_rs::SeleniumBaseError> {    let mut builder = LaunchOptions::builder();    // Without SB_HEADLESS, the engine's default for the system stays.    if std::env::var_os("SB_HEADLESS").is_some() {        builder = builder.headless(Settings::from_env()?.headless);    }    builder.build()}

Settings::load() and sbrs look for sbase_config.toml, then .sbase_config.toml, then .sbase_config (JSON) in the current directory:

headless = true

{ "headless": true }

SB_HEADLESS overrides the file, and an sbrs flag overrides both. sbrs --config FILE reads another file instead. See Settings.

The start_browser tool of every sbrs-mcp toolset takes a headless argument: true forces headless and false forces headed. Without it, the browser is headless on Linux and headed elsewhere. The server does not read SB_HEADLESS.

{ "headless": true }

See MCP servers.

A Chromium session starts at 1280 by 720 pixels (390 by 844 with with_mobile(true)) unless with_window_size sets another size. set_window_size resizes a running browser, and reset_window_size goes back to 1280 by 720.

use seleniumbase_rs::browser::options::WindowSize;use seleniumbase_rs::BrowserConfig;let config = BrowserConfig::default().with_window_size(WindowSize::new(1920, 1080));// Inside the test:sb.set_window_size(1366, 768).await?;let (width, height) = sb.get_window_size().await?;

Without window_size, the pure CDP engine passes no size and Chrome keeps its own, unless a fingerprint gives a screen size. page.window() resizes and reads a running window.

use seleniumbase_rs::sb_cdp::LaunchOptions;let options = LaunchOptions::builder()    .headless(true)    .window_size(1920, 1080)    .build()?;// On a page of the running browser:page.window().set_bounds(0, 0, 1366, 768).await?;let bounds = page.window().bounds().await?;println!("{} by {}", bounds.width, bounds.height);

sbrs takes the size from SB_WINDOW_WIDTH and SB_WINDOW_HEIGHT, or from window_width and window_height in the settings file. Set both, or neither. --mobile gives a 390 by 844 window and an Android user agent.

SB_WINDOW_WIDTH=1920 SB_WINDOW_HEIGHT=1080 sbrs --headless open https://example.comsbrs --headless --mobile open https://example.com

save_screenshot and save_element_as_image_file write into the logs folder (latest_logs/) and take a plain file name. save_screenshot_to_path writes to the path you give, and screenshot_as_png returns the bytes.

let shot = sb.save_screenshot("home.png").await?;let heading = sb.save_element_as_image_file("h1", "heading.png").await?;sb.save_screenshot_to_path(std::env::temp_dir().join("home.png")).await?;let png = sb.screenshot_as_png().await?;

page.screenshot() captures the viewport as PNG bytes. A locator’s screenshot() scrolls the element into view and captures its box at scale 1, also the part that reaches past the window.

std::fs::write("home.png", page.screenshot().await?)?;std::fs::write("heading.png", page.locator("h1").screenshot().await?)?;

Printing goes over the DevTools Protocol, so start the session in DriverMode::Cdp. print_to_pdf writes to a path, and save_as_pdf_to_logs writes into latest_logs/ and returns the path.

use seleniumbase_rs::{BrowserConfig, DriverMode};let config = BrowserConfig::default().with_mode(DriverMode::Cdp);// Inside the test:sb.print_to_pdf("example.pdf").await?;let pdf = sb.save_as_pdf_to_logs("example.pdf").await?;

page.pdf() returns the PDF bytes.

std::fs::write("example.pdf", page.pdf().await?)?;

sbrs print-pdf opens a URL or a local file and prints it (to page.pdf without -o). On a Chromium browser it turns CDP mode on by itself.

sbrs --headless print-pdf https://example.com -o example.pdf

download_file opens the address in a new tab, waits up to the given number of seconds for the file, and goes back to the first tab. The assertions wait up to the default timeout for a file that is still being written. All of them look in get_downloads_folder(): the system’s Downloads folder, or the working directory when the system names none.

let path = sb.download_file("https://example.com/report.csv", "report.csv", 30).await?;sb.click("a#export").await?;sb.assert_downloaded_file("export.csv").await?;sb.assert_data_in_downloaded_file("id,name", "export.csv").await?;println!("downloads go to {}", sb.get_downloads_folder().display());

download_file has the page fetch the address, with its cookies, and download_by_click clicks a link the server answers with a download. Both tell Chrome to save into the folder you give, create it, and wait, up to the page’s timeout, for the browser to report the file finished. Until a folder is given, assert_downloaded_file looks in downloaded_files/.

use std::time::Duration;page.goto("https://example.com/reports").await?;let report = page    .download_file("https://example.com/reports/report.csv", "downloads")    .await?;let export = page.download_by_click("a#export", "downloads").await?;page.assert_downloaded_file("export.csv", Duration::from_secs(10)).await?;// A slow download needs a longer wait than the default 7 seconds:let big = page    .with_timeout(Duration::from_secs(120))    .download_file("https://example.com/big.zip", "downloads")    .await?;

A file of the same name in the folder is replaced, and an address on another site needs CORS headers, because the page itself fetches it.

sbrs download-file downloads with the browser and, when that fails or takes longer than --timeout seconds (30 by default), over plain HTTP.

sbrs --headless download-file https://example.com/report.csv -o reports/report.csv

choose_file waits up to 10 seconds for the input, and the file must exist on the machine that runs the test. A relative path is read from the working directory.

sb.choose_file("input[type=file]", "fixtures/report.csv").await?;sb.click("button[type=submit]").await?;

The pure CDP engine has no upload method. The programs that sbrs import-playwright and sbrs import-puppeteer write add a helper that focuses the input and hands it to DOM.setFileInputFiles with page.execute. The same steps, with serde_json in your Cargo.toml:

use serde_json::json;page.locator("input[type=file]").focus().await?;let input = page    .execute("Runtime.evaluate", json!({ "expression": "document.activeElement" }))    .await?;let path = std::fs::canonicalize("fixtures/report.csv")?;page.execute(    "DOM.setFileInputFiles",    json!({ "files": [path.to_string_lossy()], "objectId": input["result"]["objectId"] }),).await?;

sbrs choose-file opens --url (or a blank page with a file input) and puts the file into the input the selector names.

sbrs --headless choose-file --url https://example.com/upload 'input[type=file]' fixtures/report.csv

The alert methods work the same headless. Read the text before you answer; dismiss_alert is the Cancel button.

sb.click("#delete").await?; // the page calls confirm("Delete?")let question = sb.get_alert_text().await?;sb.accept_alert().await?;sb.click("#rename").await?; // the page calls prompt("New name")sb.type_alert_text("Ada").await?;sb.accept_alert().await?;sb.click("#later").await?; // the alert opens after a delaysb.wait_for_and_accept_alert(5).await?;

The pure CDP engine has no dialog methods. Replace the page’s dialog functions before the step that would open one, so none opens. add_init_script covers every page the tab loads from now on, and evaluate covers the page already open.

let answers = "window.alert = () => {}; \               window.confirm = () => true; \               window.prompt = () => 'Ada';";page.add_init_script(answers).await?;page.evaluate(answers).await?;page.locator("#delete").click().await?;

execute_script runs the script as the body of a function, so return the value you want. It comes back as a serde_json::Value.

let title = sb.execute_script("return document.title;").await?;let links = sb.execute_script("return document.links.length;").await?;println!("{} has {} links", title.as_str().unwrap_or_default(), links);

evaluate takes an expression, waits for a promise, and returns a serde_json::Value. evaluate_as turns the result into a Rust type. A return at the start of the last line is dropped, so a WebDriver-style script works too.

let title: String = page.evaluate_as("document.title").await?;let links: u64 = page.evaluate_as("document.links.length").await?;let status = page.evaluate("fetch('/').then(r => r.status)").await?;

The WebDriver engine has no HAR recorder. Use the pure CDP engine.

start_har records the tab’s requests, and those of its iframes, from the moment it returns, so start it before the navigation. Response bodies are left out unless you ask for them with start_har_with.

use seleniumbase_rs::sb_cdp::HarOptions;// start_har() keeps no bodies; this keeps each one up to 1 MiB.let recorder = page.start_har_with(HarOptions::new().content(true)).await?;page.goto("https://example.com").await?;let har = recorder.finish().await?;println!("{} requests", har.log.entries.len());har.save("example.har")?;

get_page_source returns the HTML, and save_page_source_to_logs saves it in latest_logs/. start_recording_console_logs wraps console.log in the current document, so start it after the page loads and read the lines before it navigates. assert_no_js_errors reads the browser’s own log, which only Chromium browsers keep, and fails on its SEVERE entries.

let html = sb.get_page_source().await?;let saved = sb.save_page_source_to_logs().await?;sb.start_recording_console_logs().await?;sb.click("#run").await?;let lines = sb.get_recorded_console_logs().await?;sb.assert_no_js_errors().await?;

page.content() returns the HTML as scripts left it. js_errors lists the uncaught errors and unhandled promise rejections of the current document. The engine has no recorder for console.log.

let html = page.content().await?;let errors = page.js_errors().await?;page.assert_no_js_errors().await?;

with_device_metrics turns on Chrome’s phone emulation: the page sees that viewport, a touch screen and that pixel ratio, with an Android user agent unless with_user_agent gives one. with_mobile(true) alone only gives a 390 by 844 window and the Android user agent. with_locale sets the language. set_timezone and set_geolocation change a running browser and need CDP mode. BaseCase has no method that grants the location permission.

use seleniumbase_rs::browser::options::DeviceMetrics;use seleniumbase_rs::{BrowserConfig, DriverMode};let config = BrowserConfig::default()    .with_mode(DriverMode::Cdp)    .with_device_metrics(DeviceMetrics::new(412, 915, 2.625))    .with_locale("de-DE");// Inside the test:sb.set_timezone("Europe/Berlin").await?;sb.set_geolocation(52.52, 13.405, 10.0).await?;

page.emulation() changes what one tab reports, and the location also needs the permission. Replacing HeadlessChrome in the user agent hides the most visible headless sign. The pure CDP engine has no phone emulation: set the window size and user agent, or a fingerprint (see Fingerprints and stealth).

use seleniumbase_rs::sb_cdp::Permission;let emulation = page.emulation();emulation.timezone("Europe/Berlin").await?;page.browser().grant_permissions(&[Permission::Geolocation]).await?;emulation.geolocation(52.52, 13.405, 10.0).await?;let agent = page.user_agent().await?.replace("HeadlessChrome", "Chrome");emulation.user_agent(&agent, None).await?;

For the language, LaunchOptionsBuilder::lang sets it at launch, and emulation.locale from the next page load. LaunchOptionsBuilder::user_agent sets the user agent at launch.

--mobile (a 390 by 844 window and an Android user agent), --locale and --user-agent (or -a) are global options. The command line cannot set a time zone or a location.

sbrs --headless --mobile --locale de-DE open https://example.com