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.1.16"

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::remote::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
}

/// Initializes 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)
}

/// Retrieves 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 {idx}");
    }
}

/// Navigates to the specified URL and waits 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

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.