Migrate Python Tests

Moving an existing Python SeleniumBase or Selenium WebDriver test suite to Rust is rarely a pure translation exercise. Tests often contain dynamic expressions, custom helpers, fixtures, and framework plugins that cannot be converted automatically. The sbrs import-python command is designed to handle the mechanical parts and surface the parts that need human review.

This page explains how to use the importer, what it can and cannot translate, and how to validate the generated Rust.

When to use the importer#

Use sbrs import-python when:

• You have many simple, linear tests that mostly navigate, click, type, and assert.
• You want a starting point for a manual migration.
• You need to compare the original Python with generated Rust side by side.

Convert a file from the CLI#

cargo run --bin sbrs -- import-python tests/login_test.py --output tests/login_test.rs

The tool reads the Python file, detects whether it looks like SeleniumBase or plain Selenium WebDriver, and writes a Rust test that uses #[tokio::test] and run_browser_test.

Diagnostics are printed to standard error. If you omit --output, the generated Rust is written to standard output so you can inspect it before saving. Unless you pass --test-name, the test function is named after the Python file (login_test here). The file is written even when there are problems, but the command then exits with an error if any diagnostic has the Error severity.

The importer skips import, from, def, class, decorator and with SB( lines and reads the statements that remain, so every statement in the file ends up in one generated test, even when the Python file has several test methods.

Override detection#

The importer tries to detect the source API automatically, but you can override it:

cargo run --bin sbrs -- import-python tests/login_test.py \  --source selenium \  --test-name user_can_log_in \  --output tests/login_test.rs

What the importer converts#

The importer reads one statement at a time and understands these. In all cases the arguments must be string (or, for waits and sleep, number) literals. Arguments are matched with Python’s parameters, so selector="#a" and timeout=5 work as well as positional ones, and a left-out selector is body, as in Python.

What requires manual review#

The importer is conservative. Anything it does not understand is emitted as a TODO comment or a diagnostic. Common cases that need manual work include:

• Dynamic expressions and string formatting for selectors or URLs.
• Control flow such as loops, conditionals, and try/except blocks.
• Complex XPath that has no CSS equivalent.
• Custom helpers and page-object classes.
• Pytest fixtures, parametrization, and plugins.
• File uploads, downloads, and non-standard API calls.
• Selenium WebDriverWait, Select(...).select_by_visible_text, ActionChains and keyboard chords for send_keys.

A statement the importer does not recognise becomes a TODO comment and a Warning diagnostic. One it recognises but cannot translate safely (a non-literal argument, an XPath with no CSS equivalent, an unknown By strategy) becomes a TODO comment and an Error diagnostic, which makes the CLI exit with an error.

Example conversion#

Given this Python file, the importer produces the Rust file next to it (the layout is rustfmt-able but not formatted):

from seleniumbase import BaseCaseclass LoginTest(BaseCase):    def test_login(self):        self.open("https://example.com/login")        self.type("#username", "alice")        self.type("#password", "secret")        self.click("#submit")        self.assert_text("Welcome", "body")

use seleniumbase_rs::{BrowserConfig, run_browser_test};#[tokio::test]async fn login_test() -> seleniumbase_rs::Result<()> {    run_browser_test(BrowserConfig::default(), async |sb| {        sb.open("https://example.com/login").await?;        sb.type_text("#username", "alice").await?;        sb.type_text("#password", "secret").await?;        sb.click("#submit").await?;        sb.assert_text("Welcome", "body").await?;        Ok(())    }).await}

Validate the generated Rust#

After conversion, run these steps before trusting the test:

Programmatic API#

The same importer is available from Rust code through import_python, ImportOptions, and PythonSource:

use seleniumbase_rs::{    import_python, ImportOptions, ImportResult, PythonSource,};# fn main() -> Result<(), Box<dyn std::error::Error>> {let python = std::fs::read_to_string("tests/login_test.py")?;let result: ImportResult = import_python(    &python,    &ImportOptions {        source: PythonSource::Auto,        test_name: "login".to_owned(),    },);println!("{}", result.rust);for diagnostic in &result.diagnostics {    eprintln!("{:?} at line {}: {}", diagnostic.severity, diagnostic.line, diagnostic.message);}if !result.is_complete() {    eprintln!("error-level diagnostics: review the TODO comments");}# Ok(())# }

result.detected_source says which API family the importer assumed, and result.is_complete() is true when no diagnostic has the Error severity.

Migration strategy#

For large suites, a full automated migration is usually not practical. A more realistic approach is:

Related reading#