0
# Selenium Chromium Driver
1

2
Selenium Chromium Driver is a specialized WebDriver implementation that provides a unified interface for controlling Chromium-based browsers (Chrome, Edge, Opera) in automated testing and web scraping scenarios. It extends Selenium's core remote WebDriver functionality with Chromium-specific capabilities including Chrome DevTools Protocol (CDP) support, network conditions manipulation, permissions management, application launching, and media casting features.
3

4
## Package Information
5

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

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

20
## Core Imports
21

22
```java
23
import org.openqa.selenium.chrome.ChromeDriver;
24
import org.openqa.selenium.chrome.ChromeOptions;
25
import org.openqa.selenium.chrome.ChromeDriverService;
26
import org.openqa.selenium.chrome.ChromeDriverInfo;
27
import org.openqa.selenium.chromium.ChromiumNetworkConditions;
28
import org.openqa.selenium.chromium.HasCdp;
29
import org.openqa.selenium.chromium.HasCasting;
30
import org.openqa.selenium.chromium.HasNetworkConditions;
31
import org.openqa.selenium.chromium.HasPermissions;
32
import org.openqa.selenium.chromium.HasLaunchApp;
33
```
34

35
## Basic Usage
36

37
```java
38
import org.openqa.selenium.chrome.ChromeDriver;
39
import org.openqa.selenium.chrome.ChromeOptions;
40
import org.openqa.selenium.chrome.ChromeDriverService;
41

42
// Basic Chrome driver usage with default service and options
43
ChromeDriver driver = new ChromeDriver();
44

45
// Configure Chrome options
46
ChromeOptions options = new ChromeOptions();
47
options.addArguments("--headless", "--no-sandbox");
48
options.setBinary("/path/to/chrome");
49

50
// Create driver with options
51
ChromeDriver driverWithOptions = new ChromeDriver(options);
52

53
// Using custom service
54
ChromeDriverService service = ChromeDriverService.createDefaultService();
55
ChromeDriver driverWithService = new ChromeDriver(service, options);
56

57
// Use standard WebDriver methods
58
driver.get("https://example.com");
59
String title = driver.getTitle();
60

61
// Use Chrome-specific features (available through interfaces)
62
if (driver instanceof HasPermissions) {
63
    ((HasPermissions) driver).setPermission("camera", "granted");
64
}
65
if (driver instanceof HasLaunchApp) {
66
    ((HasLaunchApp) driver).launchApp("chrome-app-id");
67
}
68

69
// Clean up
70
driver.quit();
71
```
72

73
## Architecture
74

75
The Selenium Chromium Driver is built around several key components:
76

77
- **ChromiumDriver**: Main WebDriver implementation extending RemoteWebDriver with Chromium-specific interfaces
78
- **ChromiumOptions**: Configuration system for browser setup, extensions, and experimental features
79
- **Capability Interfaces**: Modular interfaces (HasCdp, HasCasting, etc.) that define specific browser capabilities
80
- **DevTools Integration**: Chrome DevTools Protocol support for advanced debugging and automation
81
- **Network Simulation**: ChromiumNetworkConditions for testing under various network scenarios
82
- **Augmenter System**: AddHas* classes for dynamically adding capabilities to existing WebDriver instances
83

84
## Capabilities
85

86
### Chrome Driver
87

88
Chrome-specific WebDriver implementation providing seamless integration with Google Chrome browser.
89

90
```java { .api }
91
public class ChromeDriver extends ChromiumDriver {
92
  public ChromeDriver();
93
  public ChromeDriver(ChromeDriverService service);
94
  public ChromeDriver(ChromeOptions options);
95
  public ChromeDriver(ChromeDriverService service, ChromeOptions options);
96
  public ChromeDriver(ChromeDriverService service, ChromeOptions options, ClientConfig clientConfig);
97
  
98
  public static RemoteWebDriverBuilder builder();
99
}
100

101
public class ChromeOptions extends ChromiumOptions<ChromeOptions> {
102
  public static final String CAPABILITY = "goog:chromeOptions";
103
  public static final String LOGGING_PREFS = "goog:loggingPrefs";
104
  
105
  public ChromeOptions();
106
  public ChromeOptions merge(Capabilities extraCapabilities);
107
}
108

109
public class ChromeDriverService extends DriverService {
110
  public static final String CHROME_DRIVER_NAME = "chromedriver";
111
  public static final String CHROME_DRIVER_EXE_PROPERTY = "webdriver.chrome.driver";
112
  
113
  public static ChromeDriverService createDefaultService();
114
  public String getDriverName();
115
  public String getDriverProperty();
116
  public Capabilities getDefaultDriverOptions();
117
}
118
```
119

120
[WebDriver Operations](./webdriver-operations.md)
121

122
### WebDriver Core Functionality
123

124
Standard WebDriver operations with Chromium-specific enhancements including script pinning, authentication handling, and enhanced element interaction.
125

126
```java { .api }
127
public class ChromiumDriver extends RemoteWebDriver {
128
  public ScriptKey pin(String script);
129
  public Set<ScriptKey> getPinnedScripts();
130
  public void unpin(ScriptKey key);
131
  public Object executeScript(ScriptKey key, Object... args);
132
  public <X> void onLogEvent(EventType<X> kind);
133
  public void register(Predicate<URI> whenThisMatches, Supplier<Credentials> useTheseCredentials);
134
}
135
```
136

137
### Browser Configuration
138

139
Comprehensive browser configuration including binary paths, command line arguments, extensions, and Android-specific settings.
140

141
```java { .api }
142
public abstract class ChromiumOptions<T extends ChromiumOptions<?>> {
143
  public T setBinary(String path);
144
  public T addArguments(String... arguments);
145
  public T addExtensions(File... paths);
146
  public T addEncodedExtensions(String... encoded);
147
  public T setExperimentalOption(String name, Object value);
148
  public T enableBiDi();
149
}
150
```
151

152
[Browser Configuration](./browser-configuration.md)
153

154
### Chrome DevTools Protocol
155

156
Execute Chrome DevTools Protocol commands for advanced browser control and debugging capabilities.
157

158
```java { .api }
159
public interface HasCdp {
160
  Map<String, Object> executeCdpCommand(String commandName, Map<String, Object> parameters);
161
}
162
```
163

164
[DevTools Protocol](./devtools-protocol.md)
165

166
### Network Conditions Simulation
167

168
Simulate various network conditions for testing applications under different connectivity scenarios.
169

170
```java { .api }
171
public interface HasNetworkConditions {
172
  ChromiumNetworkConditions getNetworkConditions();
173
  void setNetworkConditions(ChromiumNetworkConditions networkConditions);
174
  void deleteNetworkConditions();
175
}
176

177
public class ChromiumNetworkConditions {
178
  public boolean getOffline();
179
  public void setOffline(boolean offline);
180
  public Duration getLatency();
181
  public void setLatency(Duration latency);
182
  public int getDownloadThroughput();
183
  public void setDownloadThroughput(int downloadThroughput);
184
  public int getUploadThroughput();
185
  public void setUploadThroughput(int uploadThroughput);
186
}
187
```
188

189
[Network Conditions](./network-conditions.md)
190

191
### Media Casting
192

193
Cast media content to available devices using Chrome's casting capabilities.
194

195
```java { .api }
196
public interface HasCasting {
197
  List<Map<String, String>> getCastSinks();
198
  void selectCastSink(String deviceName);
199
  void startDesktopMirroring(String deviceName);
200
  void startTabMirroring(String deviceName);
201
  String getCastIssueMessage();
202
  void stopCasting(String deviceName);
203
}
204
```
205

206
[Media Casting](./media-casting.md)
207

208
### Permissions Management
209

210
Manage browser permissions for camera, microphone, geolocation, and other web APIs.
211

212
```java { .api }
213
public interface HasPermissions {
214
  void setPermission(String name, String value);
215
}
216
```
217

218
[Permissions Management](./permissions-management.md)
219

220
### Application Launching
221

222
Launch Chromium applications and manage app lifecycles.
223

224
```java { .api }
225
public interface HasLaunchApp {
226
  void launchApp(String id);
227
}
228
```
229

230
[Application Launching](./application-launching.md)
231

232
### Service Management
233

234
Configure and manage ChromeDriverService for advanced driver lifecycle control.
235

236
```java { .api }
237
public class ChromeDriverService extends DriverService {
238
  public static final String CHROME_DRIVER_NAME = "chromedriver";
239
  public static final String CHROME_DRIVER_EXE_PROPERTY = "webdriver.chrome.driver";
240
  public static final String CHROME_DRIVER_LOG_PROPERTY = "webdriver.chrome.logfile";
241
  public static final String CHROME_DRIVER_LOG_LEVEL_PROPERTY = "webdriver.chrome.loglevel";
242
  public static final String CHROME_DRIVER_VERBOSE_LOG_PROPERTY = "webdriver.chrome.verboseLogging";
243
  public static final String CHROME_DRIVER_SILENT_OUTPUT_PROPERTY = "webdriver.chrome.silentOutput";
244
  public static final String CHROME_DRIVER_APPEND_LOG_PROPERTY = "webdriver.chrome.appendLog";
245
  public static final String CHROME_DRIVER_ALLOWED_IPS_PROPERTY = "webdriver.chrome.withAllowedIps";
246
  public static final String CHROME_DRIVER_DISABLE_BUILD_CHECK = "webdriver.chrome.disableBuildCheck";
247
  public static final String CHROME_DRIVER_READABLE_TIMESTAMP = "webdriver.chrome.readableTimestamp";
248
  
249
  public static ChromeDriverService createDefaultService();
250
  public String getDriverName();
251
  public String getDriverProperty();
252
  public Capabilities getDefaultDriverOptions();
253
}
254

255
public static class Builder extends DriverService.Builder<ChromeDriverService, ChromeDriverService.Builder> {
256
  public Builder withAppendLog(boolean appendLog);
257
  public Builder withBuildCheckDisabled(boolean noBuildCheck);
258
  public Builder withLogLevel(ChromiumDriverLogLevel logLevel);
259
  public Builder withSilent(boolean silent);
260
  public Builder withVerbose(boolean verbose);
261
  public Builder withAllowedListIps(String allowedListIps);
262
  public Builder withReadableTimestamp(Boolean readableTimestamp);
263
}
264
```
265

266
[Service Management](./service-management.md)
267

268
## Common Types
269

270
```java { .api }
271
// Predicate for checking if browser is Chromium-based
272
public static final Predicate<String> IS_CHROMIUM_BROWSER;
273

274
// Log level enumeration
275
public enum ChromiumDriverLogLevel {
276
  ALL, INFO, DEBUG, WARNING, SEVERE, OFF;
277
  
278
  public static ChromiumDriverLogLevel fromString(String text);
279
  public static ChromiumDriverLogLevel fromLevel(Level level);
280
}
281

282
// Driver information base class
283
public abstract class ChromiumDriverInfo implements WebDriverInfo {
284
  public int getMaximumSimultaneousSessions();
285
}
286

287
// Command executor for Chromium-specific commands
288
public class ChromiumDriverCommandExecutor extends DriverCommandExecutor {
289
  public ChromiumDriverCommandExecutor(DriverService service, Map<String, CommandInfo> extraCommands);
290
  public ChromiumDriverCommandExecutor(DriverService service, Map<String, CommandInfo> extraCommands, ClientConfig clientConfig);
291
}
292
```
293

294
## Error Handling
295

296
The Chromium Driver may throw the following exceptions:
297

298
- `WebDriverException` - For general WebDriver errors
299
- `SessionNotCreatedException` - When browser session cannot be created
300
- `JavascriptException` - For JavaScript execution errors
301
- `ConnectionFailedException` - When DevTools connection fails
302
- `BiDiException` - For BiDi protocol errors
303

304
Common error scenarios include missing browser binaries, invalid extension files, network connection issues, and unsupported DevTools commands.