Selenium 4 W3C Protocol: Transitioning from DesiredCapabilities to Options classes

Direct answer

For non‑standard (vendor‑specific) capabilities, add them to the appropriate Options object with the addAdditionalCapability (or language‑equivalent) method. When a DesiredCapabilities instance is passed to a Selenium 4 driver, Selenium treats it as deprecated, merges its entries into an internal Options object, logs a deprecation warning, and forwards the merged payload using the W3C protocol.

Confirmed facts

• Selenium 4 drops the legacy JSON Wire Protocol; capabilities are serialized directly to the W3C JSON schema.
• Each browser provides a dedicated Options class (e.g., ChromeOptions, FirefoxOptions) that maps one‑to‑one with the W3C capabilities.
• The method Options.addAdditionalCapability(String name, Object value) (Java) / set_capability (Python) / AddAdditionalCapability (C#) inserts a capability unchanged into the final W3C payload.
• Passing a DesiredCapabilities object to a driver constructor is still supported for backward compatibility but triggers a deprecation warning and is internally converted to an Options instance.

Likely explanation

The W3C specification does not define every vendor flag; therefore the Options classes provide an escape hatch (addAdditionalCapability) that forwards the key‑value pair unchanged. This keeps the request compliant while allowing experimental or browser‑specific flags to reach the remote end.

Steps to migrate

1. Import the browser‑specific Options class (import org.openqa.selenium.chrome.ChromeOptions; for Java).
2. Instantiate the Options object.
3. Set standard capabilities via the typed methods (addArguments, setBinary, setAcceptInsecureCerts, etc.).
4. For any custom or experimental capability not covered by those methods, call options.addAdditionalCapability("myCustomFlag", true); (adjust syntax for your language).
5. Pass the Options instance to the driver constructor (new ChromeDriver(options)) or to RemoteWebDriver.

Missing diagnostic detail

To give the exact method name for adding a custom capability, please confirm which language binding you are using (Java, Python, C#, Ruby, or JavaScript).