ABI & API Stability

This page describes the public API surface of seleniumbase-rs, the stability guarantees that apply, and how to integrate the crate with foreign code.

Public modules#

The crate root exposes the following modules:

Crate-root re-exports#

The most common types are re-exported from the crate root for convenience:

#[macro_export] macros such as selector!, sb_test!, sb_open!, and fingerprint! are also imported from the crate root:

use seleniumbase_rs::{selector, sb_test, sb_open, fingerprint};

Capability traits#

The public API is organized into capability traits in api::traits. They are implemented by BaseCase (WebDriver) and by sb_cdp::Page (Pure CDP), and can be used to write helpers that run on either engine. None of their signatures mentions an engine’s own types:

Both engines implement the capability traits; a helper depends on the traits, not on an engine.

Use these traits when writing helpers that should work with any type exposing the same capability, or as a blueprint for adding new cross-cutting concerns:

use seleniumbase_rs::{AssertionApi, ElementApi};async fn assert_logged_in<E>(sb: &mut E) -> Result<(), seleniumbase_rs::SeleniumBaseError>where    E: ElementApi + AssertionApi,{    sb.assert_element("#dashboard").await?;    sb.assert_text("Alice", "#user-name").await}

ABI note#

If you need to drive the crate from another language, write a small extern "C" shim that accepts C-compatible arguments and internally builds a BaseCase or calls the Rust API:

#[no_mangle]pub extern "C" fn sb_open_url(url: *const c_char) {    let url = unsafe { CStr::from_ptr(url).to_string_lossy() };    // spawn runtime, create BaseCase, etc.}

The default toolchain, target, and compiler version can all change the layout of public structs.

Versioning policy#

seleniumbase-rs follows Semantic Versioning:

• Patch releases fix bugs without changing the public API.
• Minor releases add functionality in a backward-compatible way.
• Major releases may break the public API.

Feature flags#

The crate uses Cargo features to keep heavy dependencies off by default:

The experimental features scrape and impersonate were removed in 0.3.0 (see the modules above).

When adding feature-gated code, use #[cfg(feature = "...")] and declare the dependency as optional = true in Cargo.toml.

Error design#

SeleniumBaseError is a rich, structured error enum:

• Element errors carry the selector and detected strategy: ElementNotFound, ElementNotInteractable, StaleElement, InvalidSelector.
• Lifecycle errors carry the binary path or URL: BrowserLaunch, BrowserDisconnected, Navigation, SessionNotStarted.
• Subsystem errors give context without string parsing: Patcher, Stealth, Network, Download, Screenshot, Pdf, CdpDriver, Playwright, Mcp, PythonMigration.

Every error exposes:

Use the ResultExt trait to attach context:

use seleniumbase_rs::{Result, ResultExt};fn read_config(path: &str) -> Result<String> {    std::fs::read_to_string(path)        .sb_context(format!("loading config from {path}"))}

What is not covered#

API stability checklist for consumers#

• Import types from the crate root or documented public modules.
• Avoid relying on paths inside api::base_case_impls or #[doc(hidden)] items.
• Pin the crate version in production.
• Do not pass seleniumbase-rs types across FFI boundaries without a C shim.
• Test feature-gated code with the same feature set you ship.