# webdriver

> A Node.js bindings implementation for the W3C WebDriver and WebDriver Bidi protocols

Latest version **10.0.2** (published 2026-10-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install webdriver
pnpm add webdriver
yarn add webdriver
bun add webdriver
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 10.0.2 |
| Published | 2026-10-08 |
| First published | 2012-04-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.19.0 |
| Dependencies | 11 |
| Unpacked size | 432.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 9844 |
| Author | Christian Bromann |
| Maintainers | christian-bromann, wdio-user, wswebcreation-nl |
| Keywords | webdriver |

## Links

- npm: https://www.npmjs.com/package/webdriver
- Repository: https://github.com/webdriverio/webdriverio
- Homepage: https://github.com/webdriverio/webdriverio/tree/main/packages/webdriver
- Issues: https://github.com/webdriverio/webdriverio/issues
- npm.io page: https://npm.io/package/webdriver

## Dependencies (11)

- [ws](https://npm.io/package/ws.md) ^8.21.0
- [undici](https://npm.io/package/undici.md) ^8.11.2
- [@types/ws](https://npm.io/package/@types/ws.md) ^8.5.3
- [@types/node](https://npm.io/package/@types/node.md) ^22.20.4
- [@wdio/types](https://npm.io/package/@wdio/types.md) 10.0.1
- [@wdio/utils](https://npm.io/package/@wdio/utils.md) 10.0.1
- [@wdio/config](https://npm.io/package/@wdio/config.md) 10.0.1
- [@wdio/logger](https://npm.io/package/@wdio/logger.md) 10.0.0
- [deepmerge-ts](https://npm.io/package/deepmerge-ts.md) ^8.0.0
- [@wdio/protocols](https://npm.io/package/@wdio/protocols.md) 10.0.2
- [https-proxy-agent](https://npm.io/package/https-proxy-agent.md) ^7.0.6

## Recent versions

- 10.0.2 (latest) — 2026-10-08
- 10.1.0-alpha.30 (next) — 2026-10-07
- 8.46.0 (v8) — 2025-08-11
- 7.40.0 (v7) — 2024-12-18
- 9.0.0-alpha.0 (v9) — 2024-03-12
- 7.0.0-beta.4 (beta) — 2021-02-09
- 5.23.0 (latest-5) — 2020-05-25
- 5.0.0-alpha.14 (alpha) — 2018-08-08
- 10.1.0-alpha.29 — 2026-10-07
- 10.0.1 — 2026-10-07
- 10.1.0-alpha.26 — 2026-10-06
- 10.1.0-alpha.25 — 2026-10-06
- 10.1.0-alpha.19 — 2026-10-06
- 10.1.0-alpha.18 — 2026-10-06
- 10.0.0 — 2026-10-05
- … 567 more at https://npm.io/package/webdriver/versions

## README

WebDriver
=========

> A lightweight, non-opinionated implementation of the [WebDriver](https://w3c.github.io/webdriver/webdriver-spec.html) and [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/) specification including mobile commands supported by [Appium](http://appium.io/)

There are [tons](https://github.com/christian-bromann/awesome-selenium#javascript) of Selenium and WebDriver binding implementations in the Node.js world. Every one of them has an opinionated API and recommended way to use it. This binding is the most non-opinionated you will find as it just represents the [WebDriver specification](https://w3c.github.io/webdriver/webdriver-spec.html) and doesn't come with any extra or higher-level abstraction. It is lightweight and comes with support for the [WebDriver specification](https://w3c.github.io/webdriver/webdriver-spec.html) and [Appium](https://appium.io/).

The package supports the following protocols:

- [WebDriver](https://w3c.github.io/webdriver/)
- [WebDriver Bidi](https://w3c.github.io/webdriver-bidi/)
- [Appium](http://appium.io/)
- [Chromium](http://chromedriver.chromium.org/) (additional Chromedriver specific commands)
- [Selenium](https://www.selenium.dev/) (additional Selenium WebDriver specific commands)
- [Sauce Labs](https://saucelabs.com/) (Sauce Labs specific WebDriver extensions)

Commands are added to the client's protocol based on assumptions of provided capabilities. You can find more details about the commands by checking out the [`@wdio/protocols`](https://www.npmjs.com/package/@wdio/protocols) package. All commands come with TypeScript support.

## Install

To install this package from NPM run:

```sh
npm i webdriver
```

## WebDriver Example

The following example demonstrates a simple Google Search scenario:

```js
import WebDriver from 'webdriver';

const client = await WebDriver.newSession({
    path: '/',
    capabilities: { browserName: 'firefox' }
})

await client.navigateTo('https://www.google.com/ncr')

const searchInput = await client.findElement('css selector', '#lst-ib')
await client.elementSendKeys(searchInput['element-6066-11e4-a52e-4f735466cecf'], 'WebDriver')

const searchBtn = await client.findElement('css selector', 'input[value="Google Search"]')
await client.elementClick(searchBtn['element-6066-11e4-a52e-4f735466cecf'])

console.log(await client.getTitle()) // outputs "WebDriver - Google Search"

await client.deleteSession()
```

## WebDriver Bidi Example

To connect to the WebDriver Bidi protocol you have to send along a `webSocketUrl` flag to tell the browser driver to opt-in to the protocol:

```js
import WebDriver from 'webdriver'

const browser = await WebDriver.newSession({
    capabilities: {
        webSocketUrl: true,
        browserName: 'firefox'
    }
})

await browser.sessionSubscribe({ events: ['log.entryAdded'] })

/**
 * returns: {"type":"console","method":"log","realm":null,"args":[{"type":"string","value":"Hello Bidi"}],"level":"info","text":"Hello Bidi","timestamp":1657282076037}
 */
browser.on('log.entryAdded', (entryAdded) => console.log('received %s', entryAdded))

await browser.executeScript('console.log("Hello Bidi")', [])
await browser.deleteSession()
```

# Configuration

To create a WebDriver session call the `newSession` method on the `WebDriver` class and pass in your configurations:

```js
import WebDriver from 'webdriver'
const client = await WebDriver.newSession(options)
```

The following options are available:

### capabilities

<Option type="Object">

Defines the [capabilities](https://w3c.github.io/webdriver/webdriver-spec.html#capabilities) you want to run in your WebDriver session. Note: by default, it will automatically set the `webSocketUrl` to establish a [WebDriver Bidi](https://w3c.github.io/webdriver-bidi/) session, if you don't want this, make sure to set `'wdio:enforceWebDriverClassic': true` in your capabilities.

</Option>
Required: `true`

### logLevel

<Option type="String" default="info" values="trace | debug | info | warn | error | silent">

Level of logging verbosity.

</Option>

### protocol

<Option type="String" default="http" values="http | https">

Protocol to use when communicating with the Selenium standalone server (or driver).

</Option>

### hostname

<Option type="String" default="localhost">

Host of your WebDriver server.

</Option>

### port

<Option type="Number" default="undefined">

Port your WebDriver server is on.

</Option>

### path

<Option type="String" default="/">

Path to WebDriver endpoint or grid server.

</Option>

### queryParams

<Option type="Object" default="undefined">

Query parameters that are propagated to the driver server.

</Option>

### connectionRetryTimeout

<Option type="Number" default="120000">

Timeout for any WebDriver request to a driver or grid.

</Option>

### connectionRetryCount

<Option type="Number" default="3">

Count of request retries to the Selenium server.

</Option>

### bidiResponseTimeout

<Option type="Number" default="180000">

Timeout (in ms) for a WebDriver Bidi command to receive a response from the browser. Increase this if you run commands, e.g. `execute`, that legitimately take longer than the default to resolve.

</Option>

### agent

<Option type="Object" default={`{
    http: new http.Agent({ keepAlive: true }),
    https: new https.Agent({ keepAlive: true })
}`}>

Allows you to use a custom` http`/`https`/`http2` [agent](https://www.npmjs.com/package/got#agent) to make requests.

</Option>

### transformRequest

<Option type="(RequestOptions) => RequestOptions" default="none">

Function intercepting [HTTP request options](https://github.com/sindresorhus/got#options) before a WebDriver request is made to a driver.

</Option>

### transformResponse

<Option type="(Response, RequestOptions) => Response" default="none">

Function intercepting HTTP response objects after a WebDriver response has arrived.

</Option>

---
_Source: https://npm.io/package/webdriver · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._