Selenium’s “legacy protocol” is the JSON Wire Protocol, the older JSON-over-HTTP protocol that preceded the W3C WebDriver standard. Selenium 3 supported both; Selenium 4 removed JSON Wire Protocol support and uses W3C WebDriver by default. Most tests do not need a wholesale rewrite, but upgrading teams should check capability names and structure, Actions usage, and the versions of their client and remote server.
What Selenium means by “legacy protocol”
The term refers to the JSON Wire Protocol: a historical protocol that WebDriver clients used to send commands to browser implementations or a RemoteWebDriver server. It defined HTTP requests and responses, with commands mapped to methods and URL paths; examples included creating a session and finding elements. The JSON Wire Protocol specification remains available in Selenium’s documentation.
As an Amazon Associate I earn from qualifying purchases.
Selenium labels its legacy documentation obsolete and says it is retained for historical reasons, not as a recommendation to use deprecated components. See Selenium’s Legacy documentation index.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesWhat changed between Selenium 3 and Selenium 4
Selenium 3 supported both W3C WebDriver and JSON Wire Protocol. The Selenium upgrade guide notes that, around Selenium 3.11, Selenium code became compliant with the W3C WebDriver specification at level 1. It says W3C-compliant code in the latest Selenium 3 should work as expected in Selenium 4. Selenium 4 removes JSON Wire Protocol support and uses W3C WebDriver by default. Read the project’s Selenium 4 upgrade guide.
#1 Best Overall
This is a protocol change beneath the WebDriver API, not a replacement for browser automation itself. Selenium describes WebDriver as browser automation implemented through language bindings and browser-specific implementations, and identifies WebDriver as a W3C Recommendation in its WebDriver documentation.
What to check when upgrading tests
1. Standard capability names
Review capabilities sent when creating a session. Selenium’s upgrade guide lists these standard capability names: browserName, browserVersion, platformName, acceptInsecureCerts, pageLoadStrategy, proxy, timeouts, and unhandledPromptBehavior. In particular, use browserVersion rather than the old version name, and platformName rather than platform.
Rank #2
2. Vendor-specific capabilities
Non-standard capabilities need a vendor prefix. The upgrade guide illustrates grouping cloud-provider fields in a vendor-named object such as cloud:options; the correct prefix depends on the provider. Check that provider’s current instructions rather than copying an example prefix blindly. An invalid capability structure can prevent the session from starting.
3. Actions usage
The upgrade guide identifies the Actions class as another major area to review. Inspect the language-binding guidance for the Selenium versions you use and check project-specific interactions, especially if tests rely on older behavior. Do not assume a change is required in every test; follow the applicable binding’s migration instructions.
4. Client, server, and remote setup
Record the Selenium client and server versions involved in session creation, then check whether the handshake and commands depend on JSON Wire Protocol behavior. The official Selenium migration guidance establishes the Selenium protocol transition, but it does not establish a complete compatibility matrix for every third-party remote server, language binding, or Grid deployment. Confirm compatibility with the vendor or deployment documentation for your specific setup.
A practical migration sequence
- Identify the versions. Note the Selenium language binding, any Selenium server or Grid, and any third-party remote service involved.
- Update and validate capabilities. Use W3C standard names, replace
versionandplatformwhere applicable, and place provider-specific capabilities under the provider’s required vendor-prefixed key. - Review Actions interactions. Compare the project’s usage with the upgrade guide for the language binding and versions in use.
- Run a session-creation test first. If a session fails to start, inspect the capability payload and server response before debugging individual browser actions.
- Run representative tests against the actual remote setup. Include tests that use Actions and any provider-specific capabilities; validate each remote service or Grid configuration rather than assuming all behave alike.
Common migration failures and how to narrow them down
- Session creation fails after the upgrade: Check capability names and nesting first. Confirm standard keys follow W3C naming and vendor-specific keys use the required prefix and object structure.
- A remote provider rejects a capability: Compare the payload with that provider’s instructions. A provider’s extension key is not necessarily interchangeable with another provider’s.
- Tests fail around pointer or keyboard interactions: Review the test’s Actions usage against the migration notes for its language binding and Selenium version.
- Local tests pass but remote tests fail: Check the remote server, Grid, or provider versions and their W3C capability requirements. Selenium’s general upgrade guide does not promise identical behavior for every third-party deployment.
- Unsure whether an application failure is a protocol issue: First establish that the session starts and that capabilities are accepted; then isolate the failing command and compare local and remote behavior.
Screenshot a page while validating a WebDriver migration
A screenshot can help document what a test rendered, but it does not diagnose WebDriver protocol compatibility or replace a failing session test. If you need a separate screenshot API for a page, ScreenshotNeo is an option: it removes cookie banners, newsletter popups, and chat widgets before capture, and only clean shots are billed.
Or skip the browser setup
Make a single GET request to capture a page as an image. See the ScreenshotNeo API documentation for request options.
Recommended Free Tools
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server gives AI agents screenshot tools, and 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
