Crate thirtyfour 

Thirtyfour is a Selenium / WebDriver library for Rust, for automated website UI testing.

It supports the W3C WebDriver v1 spec. Tested with Chrome and Firefox, although any W3C-compatible WebDriver should work.

Getting Started

Check out The Book 📚!

Features

• All W3C WebDriver and WebElement methods supported
• Async / await support (tokio only)
• Create new browser session directly via WebDriver (e.g. chromedriver)
• Create new browser session via Selenium Standalone or Grid
• Find elements (via all common selectors e.g. Id, Class, CSS, Tag, XPath)
• Send keys to elements, including key-combinations
• Execute Javascript
• Action Chains
• Get and set cookies
• Switch to frame/window/element/alert
• Shadow DOM support
• Alert support
• Capture / Save screenshot of browser or individual element as PNG
• Chrome DevTools Protocol (CDP) — typed commands via WebDriver::cdp (feature cdp, on by default), plus optional WebSocket-based event subscription via the cdp-events feature. See the cdp module for details.
• Powerful query interface (the recommended way to find elements) with explicit waits and various predicates
• Component Wrappers (similar to Page Object Model)

Feature Flags

• rustls-tls: (Default) Use rustls to provide TLS support (via reqwest).
• native-tls: Use native TLS (via reqwest).
• component: (Default) Enable the Component derive macro (via thirtyfour-macros).
• cdp: (Default) Typed Chrome DevTools Protocol commands via WebDriver::cdp / WebElement::cdp_remote_object_id / WebElement::cdp_backend_node_id.
• cdp-events: WebSocket-backed CDP event subscription. Enables [cdp::CdpSession] and pulls in tokio-tungstenite. Off by default.
• bidi: WebDriver BiDi (W3C bidirectional protocol) — typed commands and event subscription via [WebDriver::bidi]. Pulls in tokio-tungstenite. Off by default.

Example

The following example assumes you have a compatible version of Chrome installed. WebDriver::managed auto-downloads the matching chromedriver, starts it locally, and shuts it down when the session is dropped.

use thirtyfour::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let caps = DesiredCapabilities::chrome();
    let driver = WebDriver::managed(caps).await?;

    // Navigate to https://wikipedia.org.
    driver.goto("https://wikipedia.org").await?;
    let elem_form = driver.find(By::Id("search-form")).await?;

    // Find element from element.
    let elem_text = elem_form.find(By::Id("searchInput")).await?;

    // Type in the search terms.
    elem_text.send_keys("selenium").await?;

    // Click the search button.
    let elem_button = elem_form.find(By::Css("button[type='submit']")).await?;
    elem_button.click().await?;

    // Look for header to implicitly wait for the page to load.
    driver.find(By::ClassName("firstHeading")).await?;
    assert_eq!(driver.title().await?, "Selenium - Wikipedia");

    // explicitly close the browser.
    driver.quit().await?;

    Ok(())
}

The browser will not close automatically

Rust does not have async destructors, and so whenever you forget to use WebDriver::quit the webdriver will have to block the executor to drop itself and will also ignore errors while dropping, so if you know when a webdriver is no longer used it is recommended to more or less “asynchronously drop” via a call to WebDriver::quit as in the above example. This also allows you to catch errors during quitting, and possibly panic or report back to the user

If you do not call WebDriver::quit your async executor will be blocked meaning no futures can run while quitting. The synchronous fallback also emits a tracing warning so you can spot it in logs.

Element queries and explicit waits

WebDriver::query is the recommended way to find elements. It polls until the element appears, supports filtering and chained alternatives, and produces clearer error messages when nothing matches. Custom filter functions are also supported.

The WebElement::wait_until method provides explicit waits using a variety of built-in predicates, plus an escape hatch for custom predicates.

See the query documentation for more details and examples.

Components

Components allow you to wrap a web component using smart element resolvers that can automatically re-query stale elements, and much more.

#[derive(Debug, Clone, Component)]
pub struct CheckboxComponent {
    base: WebElement,
    #[by(tag = "label", first)]
    label: ElementResolver<WebElement>,
    #[by(css = "input[type='checkbox']")]
    input: ElementResolver<WebElement>,
}

impl CheckBoxComponent {
    pub async fn label_text(&self) -> WebDriverResult<String> {
        let elem = self.label.resolve().await?;
        elem.text().await
    }

    pub async fn is_ticked(&self) -> WebDriverResult<bool> {
        let elem = self.input.resolve().await?;
        let prop = elem.prop("checked").await?;
        Ok(prop.unwrap_or_default() == "true")
    }

    pub async fn tick(&self) -> WebDriverResult<()> {
        if !self.is_ticked().await? {
            let elem = self.input.resolve().await?;
            elem.click().await?;
            assert!(self.is_ticked().await?);
        }
        Ok(())
    }
}

See the components documentation for more details.

Re-exports

pub use common::cookie;

pub use common::capabilities::chrome::ChromeCapabilities;

pub use common::capabilities::chromium::ChromiumCapabilities;

pub use common::capabilities::chromium::ChromiumLikeCapabilities;

pub use common::capabilities::edge::EdgeCapabilities;

pub use common::capabilities::firefox::FirefoxCapabilities;

pub use common::capabilities::ie::InternetExplorerCapabilities;

pub use common::capabilities::opera::OperaCapabilities;

pub use common::capabilities::safari::SafariCapabilities;

pub use common::command::By;

pub use common::log::BrowserLogEntry;

pub use common::log::LoggingPrefsLogLevel;

pub use stringmatch;

pub use common::capabilities::desiredcapabilities::*;

pub use common::cookie::*;

pub use common::keys::*;

pub use common::requestdata::*;

pub use common::types::*;

Modules

action_chain

Action chains allow for more complex user interactions with the keyboard and mouse.

alert

Alert handling.

cdp

Chrome DevTools Protocol (CDP) support — typed commands, optional event subscription via WebSocket. See cdp for the API. Chrome DevTools Protocol (CDP) support.

common

Common wrappers used by both async and sync implementations.

components

Components and component wrappers.

error

Error wrappers.

extensions

Extensions for specific browsers.

manager

Auto-download and lifetime-managed local WebDriver process management.

prelude

Allow importing the common types via use thirtyfour::prelude::*.

session

Everything related to driving the underlying WebDriver session.

support

Miscellaneous support functions for thirtyfour tests.

Macros

resolve

resolve!(x) expands to x.resolve().await?

resolve_present

resolve_present!(x) expands to x.resolve_present().await?

Structs

WebDriver

The WebDriver struct encapsulates an async Selenium WebDriver browser session.

WebDriverBuilder

Builder for WebDriver sessions that talk to an externally-managed driver (e.g. a Selenium Grid, a manually-launched chromedriver, or any W3C-compatible WebDriver server).

WebElement

The WebElement struct encapsulates a single element on a page.