Implementation:SeleniumHQ Selenium PersistentCapabilities
| Knowledge Sources | |
|---|---|
| Domains | WebDriver, Capabilities |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Concrete tool for layering capability overrides on top of a base capabilities set in a persistent, immutable fashion provided by the Selenium WebDriver library.
Description
PersistentCapabilities is an immutable implementation of the Capabilities interface that uses a layered design: it holds a base set of capabilities and an overrides set, both stored as ImmutableCapabilities. When a capability is requested, the overrides layer is checked first, falling back to the base layer. Each call to setCapability or merge returns a new PersistentCapabilities instance rather than mutating the existing one, making it safe for concurrent use and functional-style programming.
Usage
Import and use PersistentCapabilities when you need to build up capabilities incrementally in an immutable, persistent data structure pattern -- where each modification produces a new instance and the original remains unchanged. This is especially useful in scenarios where capabilities are shared across multiple configurations or threads.
Code Reference
Source Location
- Repository: SeleniumHQ_Selenium
- File: java/src/org/openqa/selenium/PersistentCapabilities.java
Signature
public class PersistentCapabilities implements Capabilities
Import
import org.openqa.selenium.PersistentCapabilities;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| (none) | No | No-arg constructor creates an empty PersistentCapabilities instance | |
| source | Capabilities |
Yes | Constructor that wraps an existing Capabilities as the base layer |
| name | String |
Yes | The capability name to set (used by setCapability)
|
| value | Object |
Yes | The capability value to set (used by setCapability)
|
| other | Capabilities |
Yes | Capabilities to merge on top (used by merge)
|
Outputs
| Name | Type | Description |
|---|---|---|
| setCapability(name, value) | PersistentCapabilities |
Returns a new instance with the given capability added as an override |
| merge(other) | Capabilities |
Returns a new PersistentCapabilities with the other capabilities layered on top |
| getCapability(name) | Object (nullable) |
Returns the value from overrides first, falling back to the base layer |
| getCapabilityNames() | Set<String> |
Returns the union of capability names from both the base and overrides layers |
| asMap() | Map<String, Object> |
Returns an unmodifiable map of all resolved capabilities |
Usage Examples
// Start with a base set of capabilities
Capabilities base = new ImmutableCapabilities("browserName", "chrome");
PersistentCapabilities persistent = new PersistentCapabilities(base);
// Each setCapability returns a new instance (original is unchanged)
PersistentCapabilities withPlatform = persistent.setCapability("platformName", "LINUX");
PersistentCapabilities withCerts = withPlatform.setCapability("acceptInsecureCerts", true);
// Merge with another set of capabilities
MutableCapabilities extra = new MutableCapabilities();
extra.setCapability("pageLoadStrategy", "eager");
Capabilities merged = withCerts.merge(extra);
// The original persistent instance remains unchanged
assert persistent.getCapability("platformName") == null;
assert withPlatform.getCapability("platformName").equals("LINUX");