0
# Selenium Remote Driver
1

2
Selenium Remote Driver is a foundational Java library that implements the W3C WebDriver wire protocol for remote browser automation. It provides comprehensive infrastructure for session management, command execution, HTTP transport, error handling, and capability negotiation across different WebDriver dialects. The library serves as the communication layer between WebDriver client code and remote browser instances, enabling scalable cross-browser testing and distributed web application automation.
3

4
## Package Information
5

6
- **Package Name**: selenium-remote-driver
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Maven Coordinates**: `org.seleniumhq.selenium:selenium-remote-driver:4.33.0`
10
- **Installation**: Add to your Maven `pom.xml`:
11

12
```xml
13
<dependency>
14
    <groupId>org.seleniumhq.selenium</groupId>
15
    <artifactId>selenium-remote-driver</artifactId>
16
    <version>4.33.0</version>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
import org.openqa.selenium.remote.RemoteWebDriver;
24
import org.openqa.selenium.remote.DesiredCapabilities;
25
import org.openqa.selenium.remote.HttpCommandExecutor;
26
import org.openqa.selenium.WebDriver;
27
import org.openqa.selenium.Capabilities;
28
import org.openqa.selenium.Platform;
29
import org.openqa.selenium.By;
30
import org.openqa.selenium.WebElement;
31
import java.util.UUID;
32
import java.util.List;
33
import java.util.Map;
34
```
35

36
## Basic Usage
37

38
```java
39
import org.openqa.selenium.remote.RemoteWebDriver;
40
import org.openqa.selenium.remote.DesiredCapabilities;
41
import java.net.URL;
42

43
// Create capabilities for the browser
44
DesiredCapabilities capabilities = new DesiredCapabilities();
45
capabilities.setBrowserName("chrome");
46
capabilities.setPlatform(Platform.ANY);
47

48
// Connect to a remote WebDriver instance
49
WebDriver driver = new RemoteWebDriver(
50
    new URL("http://selenium-grid:4444/wd/hub"), 
51
    capabilities
52
);
53

54
// Use the driver
55
driver.get("https://example.com");
56
String title = driver.getTitle();
57
driver.quit();
58
```
59

60
## Architecture
61

62
Selenium Remote Driver is built around several key architectural components:
63

64
- **Command Execution Framework**: `CommandExecutor` interface with HTTP-based implementation for sending WebDriver commands over the wire
65
- **Protocol Abstraction**: Support for multiple WebDriver dialects (W3C standard and legacy JSON Wire Protocol)
66
- **Session Management**: Complete lifecycle management for browser sessions including creation, capability negotiation, and cleanup
67
- **HTTP Infrastructure**: Comprehensive HTTP client with WebSocket support, routing, filtering, and connection management
68
- **Driver Services**: Management of native driver executables with automatic discovery and lifecycle control
69
- **Distributed Tracing**: OpenTelemetry integration for observability in distributed testing environments
70
- **Enhancement System**: Augmenter framework for dynamically adding capabilities to WebDriver instances
71

72
## Capabilities
73

74
### WebDriver Operations
75

76
Core WebDriver implementation providing the primary interface for remote browser control, including navigation, element interaction, JavaScript execution, and session management.
77

78
```java { .api }
79
@Augmentable
80
public class RemoteWebDriver implements WebDriver, JavascriptExecutor, HasCapabilities, 
81
    HasDownloads, HasFederatedCredentialManagement, HasVirtualAuthenticator, Interactive, 
82
    PrintsPage, TakesScreenshot {
83
    public RemoteWebDriver(URL remoteAddress, Capabilities capabilities);
84
    public RemoteWebDriver(CommandExecutor executor, Capabilities capabilities);
85
    
86
    // Navigation
87
    public void get(String url);
88
    public String getCurrentUrl();
89
    public String getTitle();
90
    
91
    // Element operations
92
    public WebElement findElement(By locator);
93
    public List<WebElement> findElements(By locator);
94
    
95
    // JavaScript execution
96
    public Object executeScript(String script, Object... args);
97
    public Object executeAsyncScript(String script, Object... args);
98
    
99
    // Session management
100
    public Capabilities getCapabilities();
101
    public SessionId getSessionId();
102
    public void quit();
103
}
104
```
105

106
[WebDriver Operations](./webdriver-operations.md)
107

108
### Command Execution
109

110
HTTP-based command execution framework that handles the communication protocol between WebDriver clients and remote browser instances.
111

112
```java { .api }
113
public interface CommandExecutor {
114
    Response execute(Command command) throws IOException;
115
}
116

117
public class HttpCommandExecutor implements CommandExecutor, NeedsLocalLogs {
118
    public HttpCommandExecutor(URL addressOfRemoteServer);
119
    public HttpCommandExecutor(ClientConfig config);
120
    public Response execute(Command command) throws IOException;
121
}
122

123
public class Command {
124
    public Command(SessionId sessionId, String name, Map<String, ?> parameters);
125
    public SessionId getSessionId();
126
    public String getName();
127
    public Map<String, ?> getParameters();
128
}
129
```
130

131
[Command Execution](./command-execution.md)
132

133
### HTTP Communication
134

135
Comprehensive HTTP client infrastructure with support for WebSocket connections, request/response handling, routing, and connection management.
136

137
```java { .api }
138
public interface HttpClient {
139
    HttpResponse execute(HttpRequest req);
140
    CompletableFuture<HttpResponse> executeAsync(HttpRequest req);
141
    WebSocket openSocket(HttpRequest request, WebSocket.Listener listener);
142
    void close();
143
}
144

145
public class ClientConfig {
146
    public static ClientConfig defaultConfig();
147
    public ClientConfig baseUrl(URL baseUrl);
148
    public ClientConfig withFilter(Filter filter);
149
    public ClientConfig readTimeout(Duration timeout);
150
}
151

152
public class HttpRequest {
153
    public HttpRequest(HttpMethod method, String uri);
154
    public HttpMethod getMethod();
155
    public String getUri();
156
}
157
```
158

159
[HTTP Communication](./http-communication.md)
160

161
### Driver Services
162

163
Management of native driver executables including automatic discovery, lifecycle control, and process communication.
164

165
```java { .api }
166
public abstract class DriverService {
167
    public abstract String getExecutable();
168
    public abstract URL getUrl();
169
    public void start();
170
    public void stop();
171
    public boolean isRunning();
172
    public void sendOutputTo(OutputStream outputStream);
173
}
174

175
public class DriverCommandExecutor implements CommandExecutor {
176
    public DriverCommandExecutor(DriverService service);
177
    public Response execute(Command command);
178
}
179
```
180

181
[Driver Services](./driver-services.md)
182

183
### Capabilities Management
184

185
Browser capability specification and negotiation system for defining browser requirements and configuration options.
186

187
```java { .api }
188
public class DesiredCapabilities implements MutableCapabilities {
189
    public DesiredCapabilities();
190
    public DesiredCapabilities(String browser, String version, Platform platform);
191
    public void setBrowserName(String browserName);
192
    public void setVersion(String version);
193
    public void setPlatform(Platform platform);
194
    public void setAcceptInsecureCerts(boolean acceptInsecureCerts);
195
}
196

197
public interface CapabilityType {
198
    String BROWSER_NAME = "browserName";
199
    String PLATFORM_NAME = "platformName";
200
    String BROWSER_VERSION = "browserVersion";
201
    String ACCEPT_INSECURE_CERTS = "acceptInsecureCerts";
202
}
203
```
204

205
[Capabilities Management](./capabilities-management.md)
206

207
### Distributed Tracing
208

209
OpenTelemetry-based distributed tracing support for observability in distributed testing environments.
210

211
```java { .api }
212
public interface Tracer {
213
    TraceContext getCurrentContext();
214
    Propagator getPropagator();
215
    AttributeMap createAttributeMap();
216
}
217

218
public interface Span {
219
    Span setName(String name);
220
    Span addTag(String key, String value);
221
    Span addEvent(String name);
222
    void close();
223
}
224

225
public class TracedCommandExecutor implements CommandExecutor {
226
    public TracedCommandExecutor(CommandExecutor executor, Tracer tracer);
227
    public Response execute(Command command);
228
}
229
```
230

231
[Distributed Tracing](./distributed-tracing.md)
232

233
## Types
234

235
### Core Data Types
236

237
```java { .api }
238
public class SessionId {
239
    public SessionId(String opaqueKey);
240
    public SessionId(UUID uuid);
241
    public String toString();
242
}
243

244
public class Response {
245
    public Response();
246
    public Response(SessionId sessionId);
247
    public String getState();
248
    public void setState(String state);
249
    public Object getValue();
250
    public void setValue(Object value);
251
}
252

253
public enum HttpMethod {
254
    DELETE, GET, POST, PUT
255
}
256

257
public interface Browser {
258
    Browser CHROME = create("chrome");
259
    Browser EDGE = create("msedge");
260
    Browser FIREFOX = create("firefox");
261
    Browser SAFARI = create("safari");
262
    String browserName();
263
    boolean is(String browserName);
264
}
265
```