WebDriverBiDi.NET Documentation

Welcome to the official documentation for WebDriverBiDi.NET, a comprehensive .NET client library for the WebDriver BiDi protocol.

What is WebDriverBiDi.NET?

WebDriverBiDi.NET is a low-level .NET implementation of the W3C WebDriver BiDi protocol specification. It provides a robust foundation for browser automation by enabling bidirectional communication between your .NET application and web browsers.

The library targets .NET Standard 2.0 for broad compatibility across .NET Framework, .NET Core, and modern .NET versions, and additionally ships .NET 8, .NET 9, and .NET 10 assemblies. Those modern targets are the ones marked AOT-compatible; see AOT Compatibility.

Key Features

• Full Protocol Support: Complete implementation of the WebDriver BiDi protocol specification
• Extended Modules: Support for additional W3C specifications including:
  • Permissions API
  • Web Bluetooth
  • Navigation Speculation (Prefetch)
  • User Agent Client Hints
  • Digital Credentials
• Event-Driven Architecture: Asynchronous event handling for browser events
• Type-Safe API: Strongly-typed commands and responses with full IntelliSense support
• JSON Serialization: Built on System.Text.Json for efficient communication
• Flexible Transport: Support for WebSocket and Pipe connections for different deployment scenarios
• Extensible Design: Module-based architecture allows for custom extensions

What Can You Do?

WebDriverBiDi.NET enables sophisticated browser automation scenarios:

• 📝 Console Logging: Capture JavaScript console messages and errors
• 🌐 Network Monitoring: Intercept and modify network requests and responses
• 🖱️ User Interactions: Simulate mouse, keyboard, and touch inputs
• 📜 Script Execution: Execute JavaScript with full access to page context
• 🔄 Navigation Events: Track page loads, redirects, and navigation lifecycle
• 🎭 Preload Scripts: Inject JavaScript before any page scripts execute
• 🔐 Permissions Control: Manage browser permissions programmatically
• 💾 Storage Management: Interact with cookies

Quick Example

BiDiDriver driver = new(TimeSpan.FromSeconds(10));
await driver.StartAsync(webSocketUrl);

GetTreeCommandResult tree = await driver.BrowsingContext.GetTreeAsync(new());
string contextId = tree.ContextTree[0].BrowsingContextId;

await driver.BrowsingContext.NavigateAsync(
    new NavigateCommandParameters(contextId, "https://example.com")
    {
        Wait = ReadinessState.Complete
    });

EvaluateResult result = await driver.Script.EvaluateAsync(
    new EvaluateCommandParameters("document.title", new ContextTarget(contextId), true));

await driver.StopAsync();

Documentation Structure

Getting Started

• Installation and Setup
• Your First WebDriverBiDi Application
• Browser Setup Guide
• Quick Reference: a cheat sheet of the most-used commands

Core Concepts

• Understanding the Architecture
• Modules and Commands
• Events and Observables
• Working with Remote Values
• Common Pitfalls
• Protocol Reference: every specification method and the API that sends it

Module Guides

• Browser Module
• Browsing Context Module
• Script Module
• Network Module
• Input Module
• Log Module
• Session Module
• Storage Module
• Emulation Module
• Permissions Module
• Bluetooth Module
• WebExtension Module
• Speculation Module
• User Agent Client Hints Module
• Digital Credentials Module
• Additional Modules

Examples and Tutorials

• Common Scenarios
• Form Submission
• Network Interception
• Console Monitoring
• Preload Scripts

Advanced Topics

• Roslyn Analyzers
• Observability
• Structured Logging (WebDriverBiDi.Logging)
• API Design Guide
• Error Handling
• Performance Considerations
• Connection Management
• Custom Modules
• AOT Compatibility

API Reference

• Browse the complete API documentation

Important Notes

What This Library Is NOT

• Not a high-level automation framework: WebDriverBiDi.NET is a protocol implementation, not a complete automation framework like Selenium, Puppeteer, or Playwright. It is the foundation of one: Dramaturge builds automatic waiting, locators, and assertions on it.
• No browser management: The WebDriverBiDi package does not launch browsers or manage profiles; you start the browser with WebDriver BiDi enabled and connect to it (see the Browser Setup Guide). The Dramaturge.Browsers package downloads, launches, and connects to Chrome, Firefox, Edge, and Safari.
• Protocol-level API: The API closely follows the protocol specification, which may require more code for common tasks compared to higher-level frameworks.

Design Principles

• Immutable Responses: Objects received from the browser are immutable; their properties cannot be modified
• Mutable Commands: Command parameter objects have settable properties to configure the command before sending
• Async by Design: All operations are asynchronous and return Task or Task<T>

Meet Winston 🐺

Our friendly mascot Winston, the WebDriver BiDi wolf, is here to guide you on your browser automation journey! Learn about his passion for open web standards and bidirectional communication by reading Winston's story.

Getting Help

• GitHub Issues: Report bugs or request features at github.com/webdriverbidi-net/webdriverbidi-net
• Protocol Specification: Refer to the W3C WebDriver BiDi specification

Next Steps

1. Install the library and set up your development environment
2. Understand the core concepts
3. Explore the module guides
4. Try the example scenarios

---

License: MIT License
Package: Available on NuGet