# webdriver: the W3C standard that makes browsers scriptable

> The w3c/webdriver repository holds the WebDriver specification itself, a platform- and language-neutral wire protocol that lets out-of-process programs control a browser. It is a document rather than a library, so the value for an engineer is in how predictable the protocol is across implementations, and the cost is that the document has a fixed, dated version history.

**w3c/webdriver** — Remote control interface that enables introspection and control of user agents.

- Repository: https://github.com/w3c/webdriver
- Website: https://w3c.github.io/webdriver/
- Stars: 723 · Forks: 228
- Language: HTML
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/w3c-webdriver

## A protocol document, not a driver you can install

The repository contains a specification, not an implementation. The top-level entries give the shape away: index.html holds the source of the standard, webdriver-spec.html is the generated document, and there are supporting files such as w3c.json, pr-preview.json, issue.js and a results/ directory. There is no package manifest, no build output for a client library, and no released artefacts.

So the audience is narrower than for a typical open source project. The people who need this repository are writing or reviewing an implementation of WebDriver, maintaining a client library that speaks the protocol, or deciding whether to adopt the standard for their own automation work. The specification is what every driver has to match, so when a tool behaves oddly, this document is where the answer about what the standard actually says lives.

The scope is worth stating plainly. WebDriver is described as a remote control interface enabling introspection and control of user agents, providing a platform- and language-neutral wire protocol so that out-of-process programs can remotely instruct the behaviour of web browsers. It exposes interfaces to discover and manipulate DOM elements in web documents and to control the behaviour of the user agent. The stated primary intent is letting web authors write tests that automate a user agent from a separate controlling process, with the secondary case of in-browser scripts controlling a possibly separate browser.

That second case is the one most people forget. WebDriver was not designed only for external test harnesses.

## Three documents, and only one of them is still changing

The standard is authored by the W3C Browser Testing and Tools Working Group, and the repository lists three published forms of it. The Living Document lives at w3c.github.io/webdriver, Level 2 exists as a Working Draft at w3.org/TR/webdriver2/, and Level 1 stands as a Recommendation at w3.org/TR/webdriver1/.

The distinction matters in practice. A Recommendation is a stable, dated artefact: it is what an implementer can point at and say the behaviour is specified. A Working Draft is not. And the Living Document is the working copy, the one that reflects the current state of the group's thinking rather than a frozen version.

For an engineer integrating a driver, that gives two different questions with two different places to look. When you need to know what the standard guarantees so you can rely on it, Level 1 is the document with a formal status. When you need to know what the group is currently discussing or how a recent clarification reads, the Living Document is the place, with the caveat that its content can change without a version bump.

A warning about the version numbers themselves. Level 1 and Level 2 in this repository refer to the original WebDriver standard that grew out of the Selenium Remote WebDriver work, not to a claim about browser versions. Nothing in the repository ties those labels to a particular release of Chrome, Firefox or Safari.

## How a change reaches the standard, and the test suite that guards it

The contribution rules are short enough to quote, and they reveal how the document is validated. In short, you change index.html and submit a pull request with a good commit message. The important constraint is the next sentence: changes that affect behaviour must be accompanied by corresponding test changes to the Web Platform Tests repository, under its webdriver directory.

That is a strong rule and a good one. A specification whose normative changes require matching conformance tests is far harder to drift away from real browser behaviour than a prose document alone. It also means that reading only the spec gives you an incomplete picture, because the executable expectations live in a separate repository.

The document is maintained with ReSpec, which the project credits with helping maintain referential integrity and bibliographical data and handling routine tasks such as styling. To preview a change, you load index.html from disk in a browser. To check the integrity of the document, you run `make test` from the repository root.

Contributors are also asked to add their name to the Acknowledgements section in their first pull request, even for trivial fixes, with the names sorted lexicographically. The repository keeps a .mailmap file, which is the mechanism for making sure those sorted lists stay stable when people change their email addresses or employer names.

## Vendor status documents are where implementation reality lives

The specification does not decide how well each browser implements it. That is delegated to a separate set of vendor status documents, linked from the repository. The list covers Mozilla Firefox, through a Bugzilla dependency tree, Microsoft Edge, Apple Safari, the WebKit GTK port, Selenium IEDriverServer and Chrome, each pointing at that vendor's own tracking page.

This is the section to read when a question turns from what the standard says to what your driver actually does. The distinctions the vendors track are not subtle ones. A given driver might implement some commands and not others, might support a subset of the selectors, or might handle a session lifecycle edge case differently. The standard cannot resolve those questions, because a specification that only allowed one behaviour would not describe the messy reality of shipping browsers.

The practical consequence is that the spec sets the floor and the vendor pages tell you the gaps. Teams writing cross-browser test suites end up maintaining some layer of their own on top of WebDriver to smooth over those differences, and the more of that layer you write, the more you are relying on a specific driver's behaviour rather than on the protocol.

One caution about the age of some of these links. The Safari link points to documentation for macOS WebDriver commands, the WebKit GTK port is tracked in a Trac instance, and the IEDriverServer entry is a wiki page. Project hosting has moved on since those pages were written, so treat each status link as a starting point and expect some of them to lead you to a different location than their text suggests.

## Where the standard is the wrong thing to reach for

The first limitation is the obvious one but worth stating: nothing here is runnable. There is no reference client, no conformance harness in this repository, and no command to start a browser. If your problem is that your test suite is slow or flaky, the specification will not help you, because it describes the protocol and not the performance of any implementation.

The second is scope. WebDriver is a remote control interface, and the document is about commands and their semantics. It does not describe a test framework, a runner, a selector strategy layer, a reporting tool, or how to parallelise work across machines. Those all sit in projects built on top of the protocol, and picking WebDriver as the standard says nothing about which of them you will use.

The third is the friction of a normative document. Behaviour changes require matching test changes in another repository, and the spec is maintained by a working group rather than a maintainer with merge-and-ship authority. That is the right process for a standard that many implementations must match, and it is slower than shipping a library. If your requirement is a stable API you can pin and upgrade on your own schedule, a library is a better dependency, and the specification is best read as the reference that library should follow.

The last limitation concerns the license and governance, not the technology. The repository ships a LICENSE.md, and GitHub does not classify the licence as one of the standard ones it can recognise, so anyone copying text out of the specification for reuse needs to read that file directly rather than assume a permissive default. W3C specification text has its own licensing conventions, and the repository is explicit about pointing at the file.

## Conclusion

webdriver is the right reference for anyone choosing a browser automation standard, writing a client library, or debugging why one driver's behaviour differs from another's, because it is the normative text rather than one vendor's implementation of it. It is not a tool you can install, and it will not tell you which driver to pick for your CI matrix, since that choice lives in the vendor status documents rather than the spec. Before depending on a behaviour, look it up in the living document at w3c.github.io/webdriver, compare it against the dated Level 1 Recommendation and Level 2 Working Draft, and check the specific driver you plan to use, since the last push to the repository was on 2026-10-07 and the specification still moves independently of any browser release cycle.

## FAQ

### What is the WebDriver standard used for?

It is a platform- and language-neutral wire protocol that lets out-of-process programs remotely instruct a web browser, including discovering and manipulating DOM elements. It is primarily intended for writing tests that automate a user agent from a separate controlling process.

### What is the difference between the WebDriver living document, Level 1 and Level 2?

The living document at w3c.github.io/webdriver is the current working version, Level 1 at w3.org/TR/webdriver1/ is a Recommendation, and Level 2 at w3.org/TR/webdriver2/ is a Working Draft.

### How do I contribute a change to the WebDriver specification?

You change index.html and open a pull request with a good commit message, and changes that affect behaviour must come with matching test changes in the Web Platform Tests repository. Use make test to verify the integrity of the document before submitting.

### Which browsers implement WebDriver?

The repository links to vendor status pages for Mozilla Firefox, Microsoft Edge, Apple Safari, the WebKit GTK port, Selenium IEDriverServer and Chrome, so the coverage of each implementation is tracked by the vendors themselves rather than by the specification.

## Sources

- [Issues](https://github.com/w3c/webdriver/issues)
- [Project website](https://w3c.github.io/webdriver/)
- [README](https://github.com/w3c/webdriver/blob/master/README.md)
- [w3c/webdriver on GitHub](https://github.com/w3c/webdriver)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/w3c-webdriver