webdriver-precore

A typed wrapper for W3C WebDriver (HTTP and BiDi) protocols.

https://github.com/pyrethrum/webdriver-precore#readme

LTS Haskell 24.29:0.1.0.2
Stackage Nightly 2026-02-05:0.2.0.2
Latest on Hackage:0.2.0.2

See all snapshots webdriver-precore appears in

BSD-3-Clause licensed by John Walker, Adrian Glouftsis
Maintained by [email protected]
This version can be pinned in stack with:webdriver-precore-0.2.0.2@sha256:84af10064e015538fdb66d6f2696086395e87d0bdb362ec4df4544c94d8e5b4f,7376

Module documentation for 0.2.0.2

Used by 1 package in nightly-2026-02-05(full list with versions):
webdriver-precore

webdriver-precore

build Hackage Stackage Nightly

What is This Library?

This library provides typed definitions for the W3C WebDriver Protocol, supporting both the HTTP and the BiDi protocols.

This library is intended as a foundation for building WebDriver client implementations. It is type constructors only, and does not include any executable client code.

If you are writing a webdriver client, this library will save you the effort of analysing the specs and implementing the protocol types and JSON instances.

If you are looking for a library to enable you to interact with web pages directly then you need a fully implemented web client library which this library is not.

For a fully implemented webdriver client, consider an alternative such as haskell-webdriver

Why This Library?

Several libraries provide WebDriver bindings for Haskell. However, when development on this library began, the existing options were either unmaintained, dependent on Selenium, or tightly coupled with larger “batteries included” testing frameworks.

We, the authors of this library, are building our own stand-alone test framework. To support browser based testing within this framework we’re first creating a series of independent low-level libraries. This library is the first in that series. Our aim is to make each of our low level libraries broadly useful to others, outside its use within our own framework.

Core Principles

  • Direct W3C WebDriver Implementation

    • No Selenium dependency
    • Full control over protocol handling
      Note: the W3C WebDriver standard is an initiative driven largely by the core Selenium contributors. It provides a uniform HTTP API to drive browsers, and can be leveraged by any library, including Selenium.

  • Minimalist Design

    • Boring Haskell
    • Few external dependencies

  • Enable a Layered Architecture

    • Provide an unopinionated WebDriver client for use in higher level libraries

Library Non-Goals

The following features are not included in this library. They belong in downstream libraries.

  • Convenience or utility functions, that do not directly correspond to an endpoint on the W3C spec.
  • Transformers, effects or similar abstractions.
  • Bespoke variations from the spec to accommodate non-standard driver behaviour.

Acknowledgements

This library would not have been possible without the prior work in:

Haskell (particularly):

Selenium and WebDriver Standards:

The decade+ efforts of the Selenium maintainers, both in forging the way with Selenium and their ongoing work in the development of the W3C standards, both HTTP and BiDi

Further Details

For further details on the structure and use of this library see the Hackage Docs.

For runnable demos and source code for an example client implementation see the test directory of this repository.

Changes

webdriver-precore-0.2.0.1 (2026-01-17)

Breaking Changes

Module Restructure

The library has been reorganized to support both HTTP and BiDi protocols:

  • WebDriverPreCore.SpecDefinition deleted. Use WebDriverPreCore.HTTP.API or the deprecated WebDriverPreCore.HTTP.SpecDefinition
  • WebDriverPreCore.Capabilities → WebDriverPreCore.HTTP.Capabilities
  • WebDriverPreCore.HttpResponse → WebDriverPreCore.HTTP.HttpResponse

Main module exports updated to reflect new structure. Import from WebDriverPreCore.HTTP.* for HTTP protocol or WebDriverPreCore.BiDi.* for BiDi protocol.

Type Renames

  • W3Spec → Command (in WebDriverPreCore.HTTP.Protocol)
  • SessionId → Session (constructor: MkSession)
  • WebDriverErrorType → ErrorType
  • ScriptTimeoutError → ScriptTimeout
  • Error functions renamed:
    • errorCodeToErrorType → toErrorType
    • errorTypeToErrorCode → toErrorCode
    • parseWebDriverError → parseWebDriverException
    • parseWebDriverErrorType → parseErrorType

HTTP API Changes

Status endpoint: Return type changed from DriverStatus to Status. The Status type correctly implements the spec:

  • ready field indicates if server accepts commands
  • message field provides additional info
  • Previous implementation incorrectly returned ready as status

New session: Now returns SessionResponse containing:

  • sessionId :: Session (the session ID)
  • webSocketUrl :: Maybe Text (for BiDi connections)
  • capabilities :: Capabilities (matched capabilities)
  • extensions :: Maybe (Map Text Value) (extension-specific data)

Response parsing: The Command type in the new API no longer exposes a parser field. Extract the response body value and call parseJSON on it. For migration examples, see HTTP test runners.

Migration Guide

  1. Update imports:

    -- Old
import WebDriverPreCore.SpecDefinition

-- New
import WebDriverPreCore.HTTP.API

  2. Update types in code:

    -- Old
spec :: W3Spec a
sessionId :: SessionId
errType :: WebDriverErrorType

-- New  
cmd :: Command a
session :: Session
errType :: ErrorType

  3. Handle new session response:

    -- Old: newSession returned SessionId
sessionId <- runCommand $ newSession caps

-- New: newSession returns SessionResponse
sessionResp <- runCommand $ newSession caps
let session = sessionResp.sessionId       -- Session type
    wsUrl = sessionResp.webSocketUrl      -- for BiDi connection
    caps = sessionResp.capabilities       -- matched capabilities

  4. Update error handling:

    -- Old
errorCodeToErrorType code

-- New
toErrorType code

Deprecations

WebDriverPreCore.HTTP.SpecDefinition module deprecated (removal ~2027-02-01). This module provides backward compatibility with the old SpecDefinition API using the deprecated name HttpSpec for the spec type. Migrate to WebDriverPreCore.HTTP.API which uses the Command type.

New Features

BiDi Protocol Support

Complete implementation of W3C WebDriver BiDi protocol, including:

  • Session management: Connection setup, capability negotiation
  • Browsing contexts: Navigation, context management, tree traversal
  • Script evaluation: JavaScript execution, realm management, channel messaging
  • Network: Request interception, authentication, response modification
  • Input: Actions for keyboard, mouse, wheel
  • Storage: Cookie and storage partition management
  • Events: Subscriptions for logs, network events, browsing context lifecycle, script realm events
  • Emulation: User agent, viewport configuration
  • Browser: Process management, user context handling
  • WebExtensions: Install and uninstall browser extensions (experimental)

See WebDriverPreCore.BiDi.API for commands and WebDriverPreCore.BiDi.Protocol for types.

Error Handling Improvements

  • Added 17 BiDi-specific error types
  • ErrorType now derives FromJSON for direct parsing
  • Improved error-to-code conversion with proper camelCase handling

Bug Fixes

  • Status endpoint implementation corrected to match W3C spec
  • Fixed session status data structure (was incorrectly returning ready as the status value)

Examples

See test directory for HTTP and BiDi usage examples

webdriver-precore-0.1.0.2 (2025-05-17)

Fix Hackage build failure (ghc-9.8.4)

webdriver-precore-0.1.0.1 (2025-04-28)

README update - Stackage badge

webdriver-precore-0.1.0.0 (2025-04-27)

Downgrade cabal-version: from 3.12 => 3.8 for Stackage compatibility

webdriver-precore-0.0.0.4 (2025-04-21)

Fix another typo (bad repo examples link)

webdriver-precore-0.0.0.3 (2025-04-21)

A few documentation typos and bump version of Vector dependencies

webdriver-precore-0.0.0.2 (2025-04-21)

The initial release of this library.

See README for details