webdriverbidi 0.2.0

WebDriver BiDi client implementation in Rust.

webdriverbidi

Overview

The webdriverbidi library provides an interface for interacting with web browsers through the WebDriver BiDi (Bidirectional) protocol. This library allows you to create and manage WebDriver sessions, send commands, and handle responses asynchronously through WebSockets.

Features

Create and manage WebDriver BiDi sessions
Send commands
Handle events asynchronously

Getting Started

Prerequisites

Rust and Cargo installed
A WebDriver server that supports the BiDi protocol

Installation

Add the following to your Cargo.toml (the example below will also require tokio with full features):

[dependencies]
webdriverbidi = "0.2.0"

Usage

Start a WebDriver BiDi compliant server

$ geckodriver --host=localhost --port=4444
# chromedriver --host=localhost --port=4444
# ./msedgedriver --host=localhost --port=4444

Create a new Rust project and add the following code to src/main.rs:

use anyhow::Result;
use tokio::time;

use webdriverbidi::model::browsing_context::{
    GetTreeParameters, NavigateParameters, ReadinessState,
};
use webdriverbidi::session::WebDriverBiDiSession;
use webdriverbidi::webdriver::capabilities::CapabilitiesRequest;

const HOST: &str = "localhost";
const PORT: u16 = 4444;

async fn sleep_for_secs(secs: u64) {
    time::sleep(time::Duration::from_secs(secs)).await
}

/// Initialize a new WebDriver BiDi session.
pub async fn init_session() -> Result<WebDriverBiDiSession> {
    let capabilities = CapabilitiesRequest::default();
    let mut session = WebDriverBiDiSession::new(HOST.into(), PORT, capabilities);
    session.start().await?;
    Ok(session)
}

/// Retrieve the browsing context at the specified index.
pub async fn get_context(session: &mut WebDriverBiDiSession, idx: usize) -> Result<String> {
    let get_tree_params = GetTreeParameters::new(None, None);
    let get_tree_rslt = session.browsing_context_get_tree(get_tree_params).await?;
    if let Some(context_entry) = get_tree_rslt.contexts.get(idx) {
        Ok(context_entry.context.clone())
    } else {
        anyhow::bail!(
            "No browsing context found at index {}. Available contexts: {}",
            idx,
            get_tree_rslt.contexts.len()
        );
    }
}

/// Navigate to the specified URL and wait for the document to completely load.
pub async fn navigate(session: &mut WebDriverBiDiSession, ctx: String, url: String) -> Result<()> {
    let navigate_params = NavigateParameters::new(ctx, url, Some(ReadinessState::Complete));
    session.browsing_context_navigate(navigate_params).await?;
    Ok(())
}

#[tokio::main]
async fn main() -> Result<()> {
    let mut session = init_session().await?;
    let ctx = get_context(&mut session, 0).await?;

    let url = String::from("https://www.rust-lang.org/");
    navigate(&mut session, ctx, url).await?;

    sleep_for_secs(1).await;
    session.close().await?;
    Ok(())
}

Module Coverage

session

Types

session.CapabilitiesRequest
session.CapabilityRequest
session.ProxyConfiguration
session.UserPromptHandler
session.UserPromptHandlerType
session.Subscription
session.SubscriptionRequest
session.UnsubscribeByIDRequest
session.UnsubscribeByAttributesRequest

Commands

session.status
session.new
session.end
session.subscribe
session.unsubscribe

browser

Types

browser.ClientWindow
browser.ClientWindowInfo
browser.UserContext
browser.UserContextInfo

Commands

browser.close
browser.createUserContext
browser.getClientWindows
browser.getUserContexts
browser.removeUserContext
browser.setClientWindowState

browsingContext

Types

browsingContext.BrowsingContext
browsingContext.Info
browsingContext.Locator
browsingContext.Navigation
browsingContext.NavigationInfo
browsingContext.ReadinessState
browsingContext.UserPromptType

Commands

browsingContext.activate
browsingContext.captureScreenshot
browsingContext.close
browsingContext.create
browsingContext.getTree
browsingContext.handleUserPrompt
browsingContext.locateNodes
browsingContext.navigate
browsingContext.print
browsingContext.reload
browsingContext.setViewport
browsingContext.traverseHistory

Events

browsingContext.contextCreated
browsingContext.contextDestroyed
browsingContext.navigationStarted
browsingContext.fragmentNavigated
browsingContext.historyUpdated
browsingContext.domContentLoaded
browsingContext.load
browsingContext.downloadWillBegin
browsingContext.navigationAborted
browsingContext.navigationCommitted
browsingContext.navigationFailed
browsingContext.userPromptClosed
browsingContext.userPromptOpened

emulation

Commands

emulation.setGeolocationOverride

network

Types

network.AuthChallenge
network.AuthCredentials
network.BaseParameters
network.BytesValue
network.Cookie
network.CookieHeader
network.FetchTimingInfo
network.Header
network.Initiator
network.Intercept
network.Request
network.RequestData
network.ResponseContent
network.ResponseData
network.SetCookieHeader
network.UrlPattern

Commands

network.addIntercept
network.continueRequest
network.continueResponse
network.continueWithAuth
network.failRequest
network.provideResponse
network.removeIntercept
network.setCacheBehavior

Events

network.authRequired
network.beforeRequestSent
network.fetchError
network.responseCompleted
network.responseStarted

script

Types

script.Channel
script.ChannelValue
script.EvaluateResult
script.ExceptionDetails
script.Handle
script.InternalId
script.LocalValue
script.PreloadScript
script.Realm
script.PrimitiveProtocolValue
script.RealmInfo
script.RealmType
script.RemoteReference
script.RemoteValue
script.ResultOwnership
script.SerializationOptions
script.SharedId
script.StackFrame
script.StackTrace
script.Source
script.Target

Commands

script.addPreloadScript
script.disown
script.callFunction
script.evaluate
script.getRealms
script.removePreloadScript

Events

script.message
script.realmCreated
script.realmDestroyed

storage

Types

storage.PartitionKey

Commands

storage.getCookies
storage.setCookie
storage.deleteCookies

log

Types

log.LogEntry

Events

log.entryAdded

input

Types

input.ElementOrigin

Commands

input.performActions
input.releaseActions
input.setFiles

webExtension

Types

webExtension.Extension

Commands

webExtension.install
webExtension.uninstall

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.