repository·main·Indexed 23 days ago
https://github.com/stevepryde/thirtyfourA Selenium/WebDriver library for Rust providing a high-level, asynchronous API for automated website UI testing. It supports W3C WebDriver, Chrome DevTools Protocol (CDP), and WebDriver BiDi. The library integrates with the tokio runtime and provides features for element querying, browser lifecycle management, and network interception via BiDi.
thirtyfour is a Rust crate designed for automating web browsers using the WebDriver / Selenium ecosystem. It is built on top of the W3C WebDriver protocol and provides typed support for bidirectional control protocols to enable advanced automation tasks.The following recipe categories are available to help with common automation tasks:
thirtyfour implements the W3C-standard WebDriver BiDi protocol. This functionality is gated behind the bidi feature flag.A reliable interaction follows a specific sequence to ensure the element is ready and the action was successful:
.click()).Note on 'Clickable': In thirtyfour, an element is considered 'clickable' if it is both displayed and enabled, but this is not a complete guarantee of interactability.
Decide between CDP and BiDi based on your requirements:
| Requirement | Use |
|---|---|
| Cross-browser support (Chrome and Firefox) | BiDi |
| Rich Chromium-only features (Full Network, Fetch, DOM) | CDP |
| W3C-standard, future-proof bidirectional protocol | BiDi |
Accessing Network.*, Fetch.*, Runtime.*, etc. | CDP |
Resolving a WebElement to a CDP RemoteObjectId | CDP |
Both can be used in the same session. CDP is on by default; BiDi requires opting in via a capability and a feature flag.
The find() and find_all() methods are one-shot lookups that mirror the W3C WebDriver specification. They do not perform polling, do not support filters, and provide minimal error information if no match is found.
Recommendation: Use query() for almost all automation tasks. query() handles slow page loads, missing elements, and flickering DOMs much more gracefully than the one-shot find() methods.
To ensure robust and AI-friendly browser automation, follow these selector strategies:
By::Testid as the primary method for locating elements. This provides a stable contract between the application and the automation script.find() in Flows: For standard user flows (like searching), prefer query-based flows over calling find() or find_all() as one-shot APIs, unless the specific use case requires a single, immediate lookup.Components allow you to wrap pieces of UI (buttons, forms, pages) in a Rust struct to avoid brittle, repetitive selector logic. This is similar to the Page Object Model.
Key characteristics:
Component macro.base field of type WebElement which represents the outer element the component wraps.#[by(...)]) are ElementResolver types that query the DOM starting from the base element..resolve() is called, and they cache the result to avoid redundant WebDriver calls..// to stay within the component; using // will search from the document root.use thirtyfour::prelude::*;
#[derive(Debug, Clone, Component)]
pub struct SearchForm {
base: WebElement, // The <form> itself.
#[by(id = "search-input")]
input: ElementResolver<WebElement>, // The <input>.
#[by(testid = "search-submit", description = "search submit button")]
submit: ElementResolver<WebElement>, // The <button>.
}
impl SearchForm {
pub async fn search(&self, term: &str) -> WebDriverResult<()> {
self.input.resolve().await?.send_keys(term).await?;
self.submit.resolve().await?.click().await?;
Ok(())
}
}
// Usage:
let form_el = driver.query(By::Id("search-form")).single().await?;
let form: SearchForm = form_el.into(); // From<WebElement> is derived.
form.search("Selenium").await?;The recommended way to find elements is using the query() method. Unlike the lower-level find() or find_all() methods (which are one-shot operations), query() provides a builder interface that automatically polls for the element to appear.
By default, query() polls every half-second for up to 20 seconds. If the element does not appear within the timeout, it returns an error including the selector and any description provided via .desc().
Common query terminators:
.single(): Asserts that exactly one element matches the selector..first(): Selects the first element among several matches.let elem_form = driver
.query(By::Id("search-form"))
.desc("Wikipedia search form")
.single()
.await?;Choosing between ElementQuery and ElementWaiter depends on whether you are searching for an element or waiting for an existing one to change:
ElementQuery when you are looking for an element on the page. It repeatedly evaluates selectors and filters. Use query(...).wait_until_gone() if you want to wait for an element matching a specific query to disappear (this re-runs the selector/filters to ensure no replacement element matches).ElementWaiter when you already have a resolved WebElement and want to watch it reach a specific state (e.g., becoming visible, clickable, or stale). Use elem.wait_until().stale() if you want to wait for that specific remote element ID to detach from the DOM. This is useful after a click to ensure the element you acted on is gone, even if a new element matching the same selector is immediately rendered.not_exists() when you want to poll a query as a boolean rather than waiting for a timeout error.To scope lookups (similar to Playwright's locator chaining), query from a container WebElement.
Warning: Unlike Playwright Locator objects, an ElementQuery terminator resolves to a concrete WebElement. If the page re-renders, the held element may become stale. You must run the query again to re-resolve the element or use an ElementResolver within a Component for automatic stale-element recovery.
# use thirtyfour::prelude::*;
# async fn example(driver: &WebDriver) -> WebDriverResult<()> {
let dialog = driver
.query(By::Testid("delete-dialog"))
.and_displayed()
.desc("delete confirmation dialog")
.single()
.await?;
dialog
.query(By::Testid("confirm-delete"))
.and_clickable()
.desc("confirm delete button")
.single()
.await?
.click()
.await?;
# Ok(())
# }Resolvers in thirtyfour cache the resolved value to make repeated calls efficient. However, if the DOM changes (re-renders, SPA route changes, etc.), the cached WebElement may become stale.
Use these strategies to manage staleness:
resolve_present!(field) macro. This checks if the cached value is still attached to the DOM and re-queries if it is not. This is the safe default.resolve!(field) macro for better performance if the element is guaranteed to persist..invalidate() or .resolve_force() on the resolver to clear the cache.