fantoccini

To use fantoccini, you must have a WebDriver-compatible process (like geckodriver or chromedriver) running. You connect to it using ClientBuilder.

By default, you can use ClientBuilder::native() to establish a connection to a WebDriver server running on a specific URL (e.g., http://localhost:4444).

use fantoccini::{ClientBuilder, Locator};

#[tokio::main]
async fn main() -> Result<(), fantoccini::error::CmdError> {
    let c = ClientBuilder::native()
        .connect("http://localhost:4444")
        .await
        .expect("failed to connect to WebDriver");

    // ... use client ...

    c.close().await
}

WebDriverStatus

Returned by Client::status(), this struct indicates if the WebDriver is ready. It contains:

• ready: A boolean indicating if the driver can start a new session.
• message: A status message string.

Note: Some drivers like Geckodriver may return ready: false if a session is already active.

Capabilities

Capabilities is a type alias for serde_json::Map<String, serde_json::Value>, representing the dynamic set of WebDriver capabilities used during session creation.

When using issue_cmd, errors returned from the WebDriver server are encapsulated in error::CmdError.

Fantoccini follows the W3C WebDriver error handling specification:

• Successful Responses: The value field of the JSON response is extracted and returned as the result.
• Error Responses: If the HTTP status is not successful, the library parses the JSON body for error and message fields. It converts these into a error::WebDriver error, which includes the error status, the message, and optional stacktrace or data fields if provided by the server.

Instead of using deprecated methods like wait_for or wait_for_find, use the wait() method to build a structured wait operation. This allows you to wait for specific conditions, such as an element appearing on the page.

Example of waiting for an element:

let button = client.wait().for_element(Locator::Css("#my-button")).await?;

# use fantoccini::{ClientBuilder, Locator};
# #[tokio::main]
# async fn main() -> Result<(), fantoccini::error::CmdError> {
# let client = ClientBuilder::native().connect("http://localhost:4444").await.unwrap();

let button = client.wait().for_element(Locator::Css(
    r#"a.button-download[href="/learn/get-started"]"#,
)).await?;

# Ok(())
# }

In WebDriver, Actions can contain multiple ActionSequence objects. These sequences are executed in parallel using a concept called "ticks".

Each row in the Actions object represents a different input source (e.g., one row for KeyActions, one for MouseActions). Each column represents a "tick" of time.

• At each tick, all actions scheduled for that tick across all sequences are triggered simultaneously.
• A tick lasts until the longest duration of any individual action in that tick is completed (including Pause actions).
• The next tick only begins after the current tick's longest action has finished.

This allows you to synchronize complex interactions, such as pressing a key and clicking a mouse button at the exact same moment.

You can find elements on a page using the find method on a Client instance, passing a Locator. Common locators include Locator::Css for CSS selectors and Locator::LinkText for finding elements by their visible text.

Once an element is found, you can perform actions like .click().await? or retrieve attributes using .attr("attribute_name").await?.

If you need to perform low-level operations, such as downloading a file while preserving the current browser session's cookies, you can use Client::raw_client_for.

This method allows you to build a raw HTTP request for a specific URL. You can then consume the response body as a stream to read the raw bytes.

// Build a raw HTTP client request (which also has all current cookies)
let raw = img.client().raw_client_for(http::Method::GET, &src).await?;

// Read out the bytes using futures_util::TryStreamExt
use futures_util::TryStreamExt;
let pixels = raw
    .into_body()
    .try_fold(Vec::new(), |mut data, chunk| async move {
        data.extend_from_slice(&chunk);
        Ok(data)
    })
    .await
    .map_err(fantoccini::error::CmdError::from)?;
assert!(pixels.len() > 0);

fantoccini provides a specialized Form abstraction to simplify form manipulation. You first obtain a Form object by calling Client::form(locator), then use methods on that object to populate fields and submit the form.

Common methods on Form include:

• set_by_name(name, value): Sets the value of a field identified by its name attribute.
• submit(): Submits the form.

// Find the search form, fill it out, and submit it
let f = c.form(Locator::Css("#search-form")).await?;
f.set_by_name("search", "foobar").await?
 .submit().await?;