0
# Command Execution
1

2
HTTP-based command execution framework that handles the communication protocol between WebDriver clients and remote browser instances. This system provides the foundation for all WebDriver operations by translating high-level commands into HTTP requests and processing responses.
3

4
## Capabilities
5

6
### CommandExecutor Interface
7

8
Core interface for executing WebDriver commands, providing the abstraction layer between WebDriver operations and transport mechanisms.
9

10
```java { .api }
11
/**
12
 * Interface for executing WebDriver commands
13
 */
14
public interface CommandExecutor {
15
    /**
16
     * Execute a WebDriver command and return the response
17
     * @param command The command to execute
18
     * @return Response from the command execution
19
     * @throws IOException if communication fails
20
     */
21
    Response execute(Command command) throws IOException;
22
}
23
```
24

25
### HttpCommandExecutor
26

27
HTTP-based implementation of CommandExecutor that communicates with remote WebDriver endpoints using HTTP protocol.
28

29
```java { .api }
30
/**
31
 * HTTP-based command executor for communicating with remote WebDriver endpoints
32
 */
33
public class HttpCommandExecutor implements CommandExecutor, NeedsLocalLogs {
34
    
35
    // Constructors
36
    public HttpCommandExecutor(URL addressOfRemoteServer);
37
    public HttpCommandExecutor(ClientConfig config);
38
    public HttpCommandExecutor(Map<String, CommandInfo> additionalCommands, 
39
                              URL addressOfRemoteServer);
40
    public HttpCommandExecutor(Map<String, CommandInfo> additionalCommands, 
41
                              URL addressOfRemoteServer, ClientConfig config);
42
    public HttpCommandExecutor(Map<String, CommandInfo> additionalCommands, 
43
                              URL addressOfRemoteServer, HttpClient.Factory httpClientFactory);
44
    public HttpCommandExecutor(Map<String, CommandInfo> additionalCommands, 
45
                              ClientConfig config, HttpClient.Factory httpClientFactory);
46
    
47
    // Command execution
48
    public Response execute(Command command) throws IOException;
49
    
50
    // Configuration access
51
    public Map<String, CommandInfo> getAdditionalCommands();
52
    public URL getAddressOfRemoteServer();
53
    public void setLocalLogs(LocalLogs logs);
54
    
55
    // Factory methods
56
    public static HttpClient.Factory getDefaultClientFactory();
57
}
58
```
59

60
**Usage Examples:**
61

62
```java
63
import org.openqa.selenium.remote.HttpCommandExecutor;
64
import org.openqa.selenium.remote.Command;
65
import org.openqa.selenium.remote.DriverCommand;
66
import org.openqa.selenium.remote.Response;
67
import java.net.URL;
68

69
// Basic HTTP command executor
70
HttpCommandExecutor executor = new HttpCommandExecutor(
71
    new URL("http://localhost:4444/wd/hub"));
72

73
// Execute a command
74
Command command = new Command(null, DriverCommand.GET_CURRENT_URL);
75
Response response = executor.execute(command);
76

77
// With additional commands and configuration
78
Map<String, CommandInfo> customCommands = new HashMap<>();
79
customCommands.put("customCommand", 
80
    new CommandInfo("GET", "/custom/endpoint"));
81

82
HttpCommandExecutor customExecutor = new HttpCommandExecutor(
83
    customCommands, 
84
    new URL("http://localhost:4444/wd/hub"));
85
```
86

87
### TracedCommandExecutor
88

89
Command executor wrapper that adds distributed tracing support for observability in complex testing environments.
90

91
```java { .api }
92
/**
93
 * Command executor that adds distributed tracing to command execution
94
 */
95
public class TracedCommandExecutor implements CommandExecutor {
96
    
97
    public TracedCommandExecutor(CommandExecutor executor, Tracer tracer);
98
    public Response execute(Command command);
99
}
100
```
101

102
**Usage Examples:**
103

104
```java
105
import org.openqa.selenium.remote.TracedCommandExecutor;
106
import org.openqa.selenium.remote.tracing.opentelemetry.OpenTelemetryTracer;
107

108
// Wrap existing executor with tracing
109
CommandExecutor baseExecutor = new HttpCommandExecutor(gridUrl);
110
Tracer tracer = OpenTelemetryTracer.getInstance();
111
CommandExecutor tracedExecutor = new TracedCommandExecutor(baseExecutor, tracer);
112

113
// Use in RemoteWebDriver
114
RemoteWebDriver driver = new RemoteWebDriver(tracedExecutor, capabilities);
115
```
116

117
### Command
118

119
Represents a WebDriver command with session context and parameters.
120

121
```java { .api }
122
/**
123
 * Represents a WebDriver command to be executed
124
 */
125
public class Command {
126
    
127
    // Constructors
128
    public Command(SessionId sessionId, String name);
129
    public Command(SessionId sessionId, String name, Map<String, ?> parameters);
130
    public Command(SessionId sessionId, CommandPayload payload);
131
    
132
    // Accessors
133
    public SessionId getSessionId();
134
    public String getName();
135
    public Map<String, ?> getParameters();
136
}
137
```
138

139
**Usage Examples:**
140

141
```java
142
import org.openqa.selenium.remote.Command;
143
import org.openqa.selenium.remote.SessionId;
144
import org.openqa.selenium.remote.DriverCommand;
145
import java.util.Map;
146
import java.util.HashMap;
147

148
// Simple command
149
Command getTitle = new Command(sessionId, DriverCommand.GET_TITLE);
150

151
// Command with parameters
152
Map<String, Object> params = new HashMap<>();
153
params.put("url", "https://example.com");
154
Command navigate = new Command(sessionId, DriverCommand.GET, params);
155

156
// Using DriverCommand factory methods
157
Command clickElement = DriverCommand.CLICK_ELEMENT("element-id-123");
158
```
159

160
### CommandPayload
161

162
Encapsulates command name and parameters without session context.
163

164
```java { .api }
165
/**
166
 * Encapsulates command name and parameters
167
 */
168
public class CommandPayload {
169
    
170
    public CommandPayload(String name, Map<String, ?> parameters);
171
    
172
    public String getName();
173
    public Map<String, ?> getParameters();
174
}
175
```
176

177
### Response
178

179
Represents the response from a command execution, containing status, value, and session information.
180

181
```java { .api }
182
/**
183
 * Represents response from command execution
184
 */
185
public class Response {
186
    
187
    // Constructors
188
    public Response();
189
    public Response(SessionId sessionId);
190
    
191
    // Status handling (deprecated)
192
    @Deprecated
193
    public Integer getStatus();
194
    @Deprecated
195
    public void setStatus(Integer status);
196
    
197
    // State handling (W3C standard)
198
    public String getState();
199
    public void setState(String state);
200
    
201
    // Value handling
202
    public Object getValue();
203
    public void setValue(Object value);
204
    
205
    // Session handling
206
    public String getSessionId();
207
    public void setSessionId(String sessionId);
208
}
209
```
210

211
**Usage Examples:**
212

213
```java
214
import org.openqa.selenium.remote.Response;
215

216
// Process command response
217
Response response = executor.execute(command);
218
if (response.getState() != null) {
219
    // Handle error state
220
    throw new WebDriverException("Command failed: " + response.getState());
221
}
222

223
Object result = response.getValue();
224
String sessionId = response.getSessionId();
225
```
226

227
### DriverCommand Constants
228

229
Constants and factory methods for all WebDriver commands defined in the W3C specification.
230

231
```java { .api }
232
/**
233
 * Constants and factory methods for WebDriver commands
234
 */
235
public interface DriverCommand {
236
    
237
    // Session commands
238
    String NEW_SESSION = "newSession";
239
    String QUIT = "quit";
240
    
241
    // Navigation commands
242
    String GET = "get";
243
    String GO_BACK = "goBack";
244
    String GO_FORWARD = "goForward";
245
    String REFRESH = "refresh";
246
    String GET_CURRENT_URL = "getCurrentUrl";
247
    String GET_TITLE = "getTitle";
248
    String GET_PAGE_SOURCE = "getPageSource";
249
    
250
    // Element commands
251
    String FIND_ELEMENT = "findElement";
252
    String FIND_ELEMENTS = "findElements";
253
    String CLICK_ELEMENT = "clickElement";
254
    String SEND_KEYS_TO_ELEMENT = "sendKeysToElement";
255
    String GET_ELEMENT_TEXT = "getElementText";
256
    String GET_ELEMENT_TAG_NAME = "getElementTagName";
257
    String GET_ELEMENT_ATTRIBUTE = "getElementAttribute";
258
    String GET_ELEMENT_PROPERTY = "getElementProperty";
259
    String IS_ELEMENT_SELECTED = "isElementSelected";
260
    String IS_ELEMENT_ENABLED = "isElementEnabled";
261
    String IS_ELEMENT_DISPLAYED = "isElementDisplayed";
262
    String GET_ELEMENT_LOCATION = "getElementLocation";
263
    String GET_ELEMENT_SIZE = "getElementSize";
264
    String GET_ELEMENT_RECT = "getElementRect";
265
    String CLEAR_ELEMENT = "clearElement";
266
    String SUBMIT_ELEMENT = "submitElement";
267
    
268
    // JavaScript commands
269
    String EXECUTE_SCRIPT = "executeScript";
270
    String EXECUTE_ASYNC_SCRIPT = "executeAsyncScript";
271
    
272
    // Screenshot commands
273
    String SCREENSHOT = "screenshot";
274
    String ELEMENT_SCREENSHOT = "elementScreenshot";
275
    
276
    // Window commands
277
    String GET_WINDOW_HANDLES = "getWindowHandles";
278
    String GET_WINDOW_HANDLE = "getWindowHandle";
279
    String SWITCH_TO_WINDOW = "switchToWindow";
280
    String CLOSE = "close";
281
    String GET_WINDOW_SIZE = "getWindowSize";
282
    String SET_WINDOW_SIZE = "setWindowSize";
283
    String GET_WINDOW_POSITION = "getWindowPosition";
284
    String SET_WINDOW_POSITION = "setWindowPosition";
285
    String MAXIMIZE_WINDOW = "maximizeWindow";
286
    String MINIMIZE_WINDOW = "minimizeWindow";
287
    String FULLSCREEN_WINDOW = "fullscreenWindow";
288
    
289
    // Frame commands
290
    String SWITCH_TO_FRAME = "switchToFrame";
291
    String SWITCH_TO_PARENT_FRAME = "switchToParentFrame";
292
    
293
    // Alert commands
294
    String GET_ALERT_TEXT = "getAlertText";
295
    String ACCEPT_ALERT = "acceptAlert";
296
    String DISMISS_ALERT = "dismissAlert";
297
    String SET_ALERT_VALUE = "setAlertValue";
298
    
299
    // Cookie commands
300
    String ADD_COOKIE = "addCookie";
301
    String GET_ALL_COOKIES = "getCookies";
302
    String GET_COOKIE = "getCookie";
303
    String DELETE_COOKIE = "deleteCookie";
304
    String DELETE_ALL_COOKIES = "deleteAllCookies";
305
    
306
    // Timeout commands
307
    String SET_TIMEOUT = "setTimeout";
308
    
309
    // Actions commands
310
    String ACTIONS = "actions";
311
    String RELEASE_ACTIONS = "releaseActions";
312
    
313
    // Factory methods for creating command payloads
314
    static CommandPayload NEW_SESSION(Capabilities capabilities);
315
    static CommandPayload GET(String url);
316
    static CommandPayload FIND_ELEMENT(String strategy, Object value);
317
    static CommandPayload CLICK_ELEMENT(String id);
318
    static CommandPayload SEND_KEYS_TO_ELEMENT(String id, CharSequence... keys);
319
    // ... many more factory methods
320
}
321
```
322

323
**Usage Examples:**
324

325
```java
326
import org.openqa.selenium.remote.DriverCommand;
327
import org.openqa.selenium.remote.CommandPayload;
328
import org.openqa.selenium.By;
329

330
// Using command constants
331
String commandName = DriverCommand.GET_TITLE;
332

333
// Using factory methods
334
CommandPayload navigate = DriverCommand.GET("https://example.com");
335
CommandPayload findElement = DriverCommand.FIND_ELEMENT("id", "submit-button");
336
CommandPayload clickElement = DriverCommand.CLICK_ELEMENT("element-123");
337

338
// Create complete command
339
Command command = new Command(sessionId, navigate);
340
```
341

342
### CommandInfo
343

344
Represents HTTP method and URL template information for WebDriver commands.
345

346
```java { .api }
347
/**
348
 * Information about how to execute a specific command via HTTP
349
 */
350
public class CommandInfo {
351
    
352
    public CommandInfo(String method, String url);
353
    
354
    public String getMethod();
355
    public String getUrl();
356
}
357
```
358

359
### Error Handling
360

361
Comprehensive error handling for command execution failures.
362

363
```java { .api }
364
/**
365
 * Handles error responses from remote WebDriver endpoints
366
 */
367
public class ErrorHandler {
368
    
369
    public ErrorHandler();
370
    public ErrorHandler(boolean includeServerErrors);
371
    
372
    public void throwIfResponseFailed(Response response, long additionalTime);
373
    public boolean isIncludeServerErrors();
374
}
375
```
376

377
**Usage Examples:**
378

379
```java
380
import org.openqa.selenium.remote.ErrorHandler;
381

382
// Process response with error handling
383
ErrorHandler errorHandler = new ErrorHandler(true);
384
Response response = executor.execute(command);
385
errorHandler.throwIfResponseFailed(response, System.currentTimeMillis());
386
```