0
# Selenium WebDriver API
1
2
Selenium WebDriver API is the core interface for automating web browsers across different platforms and programming languages. It provides the fundamental abstractions and contracts for browser automation including WebDriver interface, element locators, capabilities, and browser interaction primitives.
3
4
## Package Information
5
6
- **Package Name**: org.seleniumhq.selenium:selenium-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency to `pom.xml`:
10
11
```xml
12
<dependency>
13
<groupId>org.seleniumhq.selenium</groupId>
14
<artifactId>selenium-java</artifactId>
15
<version>4.33.0</version>
16
</dependency>
17
```
18
19
Or to `build.gradle`:
20
21
```gradle
22
implementation 'org.seleniumhq.selenium:selenium-java:4.33.0'
23
```
24
25
## Core Imports
26
27
```java
28
import org.openqa.selenium.WebDriver;
29
import org.openqa.selenium.WebElement;
30
import org.openqa.selenium.By;
31
import org.openqa.selenium.chrome.ChromeDriver;
32
import org.openqa.selenium.support.ui.WebDriverWait;
33
import org.openqa.selenium.support.ui.ExpectedConditions;
34
```
35
36
## Basic Usage
37
38
```java
39
import org.openqa.selenium.WebDriver;
40
import org.openqa.selenium.WebElement;
41
import org.openqa.selenium.By;
42
import org.openqa.selenium.chrome.ChromeDriver;
43
import org.openqa.selenium.support.ui.WebDriverWait;
44
import org.openqa.selenium.support.ui.ExpectedConditions;
45
import java.time.Duration;
46
47
// Create a new browser instance
48
WebDriver driver = new ChromeDriver();
49
50
try {
51
// Navigate to a website
52
driver.get("https://example.com");
53
54
// Find element and interact with it
55
WebElement searchBox = driver.findElement(By.name("q"));
56
searchBox.sendKeys("selenium webdriver");
57
searchBox.submit();
58
59
// Wait for and verify results
60
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
61
WebElement results = wait.until(
62
ExpectedConditions.presenceOfElementLocated(By.id("results"))
63
);
64
65
System.out.println("Page title: " + driver.getTitle());
66
} finally {
67
// Always close the browser
68
driver.quit();
69
}
70
```
71
72
## Architecture
73
74
Selenium WebDriver API is built around several key components:
75
76
- **WebDriver Interface**: Main browser control interface providing navigation, element finding, and window management
77
- **WebElement Interface**: HTML element interaction interface for clicking, typing, and querying element properties
78
- **Element Locators**: `By` class providing various strategies to locate elements (ID, XPath, CSS selectors, etc.)
79
- **Browser Drivers**: Browser-specific implementations (ChromeDriver, FirefoxDriver, EdgeDriver, SafariDriver)
80
- **Support Utilities**: Higher-level utilities like explicit waits, page object support, and complex user interactions
81
- **Capabilities System**: Configuration management for browser options, proxies, and platform-specific settings
82
83
## Capabilities
84
85
### Core WebDriver Interface
86
87
Primary interface for browser automation providing navigation, element finding, window management, and session control.
88
89
```java { .api }
90
interface WebDriver extends SearchContext {
91
void get(String url);
92
String getCurrentUrl();
93
String getTitle();
94
String getPageSource();
95
void quit();
96
void close();
97
Set<String> getWindowHandles();
98
String getWindowHandle();
99
TargetLocator switchTo();
100
Navigation navigate();
101
Options manage();
102
}
103
```
104
105
[Core WebDriver](./webdriver.md)
106
107
### Element Interaction
108
109
Comprehensive interface for interacting with HTML elements including clicking, typing, querying properties, and taking screenshots.
110
111
```java { .api }
112
interface WebElement extends SearchContext, TakesScreenshot {
113
void click();
114
void submit();
115
void sendKeys(CharSequence... keysToSend);
116
void clear();
117
String getTagName();
118
String getDomAttribute(String name);
119
String getDomProperty(String name);
120
String getAttribute(String name);
121
String getAriaRole();
122
String getAccessibleName();
123
boolean isSelected();
124
boolean isEnabled();
125
boolean isDisplayed();
126
String getText();
127
String getCssValue(String propertyName);
128
Point getLocation();
129
Dimension getSize();
130
Rectangle getRect();
131
}
132
```
133
134
[Element Interaction](./elements.md)
135
136
### Element Location Strategies
137
138
Factory class providing various strategies to locate elements in the DOM including ID, XPath, CSS selectors, text-based searches, and modern spatial locators.
139
140
```java { .api }
141
abstract class By {
142
static By id(String id);
143
static By name(String name);
144
static By className(String className);
145
static By tagName(String tagName);
146
static By xpath(String xpathExpression);
147
static By cssSelector(String cssSelector);
148
static By linkText(String linkText);
149
static By partialLinkText(String partialLinkText);
150
}
151
152
class RelativeLocator {
153
static RelativeBy with(By by);
154
}
155
```
156
157
[Element Location](./locators.md)
158
159
### Browser Configuration
160
161
Comprehensive capability system for configuring browser options, proxy settings, platform preferences, and authentication.
162
163
```java { .api }
164
interface Capabilities {
165
String getBrowserName();
166
String getBrowserVersion();
167
Platform getPlatform();
168
String getPlatformName();
169
Object getCapability(String capabilityName);
170
Set<String> getCapabilityNames();
171
Map<String, Object> asMap();
172
}
173
174
class MutableCapabilities implements Capabilities {
175
MutableCapabilities setCapability(String name, Object value);
176
MutableCapabilities merge(Capabilities other);
177
}
178
```
179
180
[Browser Configuration](./configuration.md)
181
182
### Explicit Waits and Conditions
183
184
Sophisticated waiting mechanisms for handling dynamic content, with pre-built conditions and custom wait logic support.
185
186
```java { .api }
187
class WebDriverWait extends FluentWait<WebDriver> {
188
WebDriverWait(WebDriver driver, Duration timeout);
189
<V> V until(Function<WebDriver, V> isTrue);
190
<V> V until(ExpectedCondition<V> condition);
191
}
192
193
class ExpectedConditions {
194
static ExpectedCondition<WebElement> presenceOfElementLocated(By locator);
195
static ExpectedCondition<WebElement> visibilityOfElementLocated(By locator);
196
static ExpectedCondition<WebElement> elementToBeClickable(By locator);
197
static ExpectedCondition<Boolean> textToBePresentInElement(WebElement element, String text);
198
static ExpectedCondition<Boolean> titleIs(String title);
199
static ExpectedCondition<Alert> alertIsPresent();
200
}
201
```
202
203
[Waits and Conditions](./waits.md)
204
205
### Complex User Interactions
206
207
Advanced interaction capabilities including mouse actions, keyboard input, drag-and-drop operations, and action chaining.
208
209
```java { .api }
210
class Actions {
211
Actions(WebDriver driver);
212
Actions click();
213
Actions click(WebElement target);
214
Actions doubleClick();
215
Actions doubleClick(WebElement target);
216
Actions contextClick();
217
Actions contextClick(WebElement target);
218
Actions dragAndDrop(WebElement source, WebElement target);
219
Actions dragAndDropBy(WebElement source, int xOffset, int yOffset);
220
Actions keyDown(Keys key);
221
Actions keyUp(Keys key);
222
Actions sendKeys(CharSequence... keys);
223
Actions moveToElement(WebElement target);
224
Actions moveByOffset(int xOffset, int yOffset);
225
Actions pause(Duration duration);
226
void perform();
227
}
228
```
229
230
[User Interactions](./interactions.md)
231
232
### Browser-Specific Drivers
233
234
Concrete WebDriver implementations for major browsers with browser-specific configuration options and capabilities.
235
236
```java { .api }
237
class ChromeDriver implements WebDriver, JavascriptExecutor, TakesScreenshot, HasAuthentication, HasBiDi, HasDevTools {
238
ChromeDriver();
239
ChromeDriver(ChromeOptions options);
240
}
241
242
class ChromeOptions extends MutableCapabilities {
243
ChromeOptions addArguments(String... arguments);
244
ChromeOptions addArguments(List<String> arguments);
245
ChromeOptions addExtensions(File... paths);
246
ChromeOptions setExperimentalOption(String name, Object value);
247
ChromeOptions setHeadless(boolean headless);
248
ChromeOptions setBinary(String path);
249
}
250
```
251
252
[Browser Drivers](./drivers.md)
253
254
### Page Object Model Support
255
256
Utilities for implementing the Page Object Model pattern including element initialization, locator annotations, and event handling.
257
258
```java { .api }
259
class PageFactory {
260
static void initElements(WebDriver driver, Object page);
261
static void initElements(ElementLocatorFactory factory, Object page);
262
}
263
264
@interface FindBy {
265
String id() default "";
266
String name() default "";
267
String className() default "";
268
String tagName() default "";
269
String xpath() default "";
270
String css() default "";
271
String linkText() default "";
272
String partialLinkText() default "";
273
}
274
```
275
276
[Page Object Model](./page-objects.md)
277
278
### JavaScript Execution
279
280
Interface for executing JavaScript code in the browser context with support for synchronous/asynchronous execution and script pinning.
281
282
```java { .api }
283
interface JavascriptExecutor {
284
Object executeScript(String script, Object... args);
285
Object executeAsyncScript(String script, Object... args);
286
ScriptKey pin(String script);
287
void unpin(ScriptKey key);
288
Set<ScriptKey> getPinnedScripts();
289
Object executeScript(ScriptKey key, Object... args);
290
}
291
```
292
293
[JavaScript Execution](./javascript.md)
294
295
### Alert and Dialog Handling
296
297
Interface for interacting with JavaScript alerts, prompts, and confirmation dialogs.
298
299
```java { .api }
300
interface Alert {
301
void dismiss();
302
void accept();
303
String getText();
304
void sendKeys(String keysToSend);
305
}
306
```
307
308
[Alert Handling](./alerts.md)
309
310
## Core Types
311
312
### Common Data Types
313
314
```java { .api }
315
class Cookie {
316
Cookie(String name, String value);
317
Cookie(String name, String value, String domain, String path, Date expiry, boolean isSecure, boolean isHttpOnly, String sameSite);
318
String getName();
319
String getValue();
320
String getDomain();
321
String getPath();
322
Date getExpiry();
323
boolean isSecure();
324
boolean isHttpOnly();
325
String getSameSite();
326
}
327
328
class Dimension {
329
Dimension(int width, int height);
330
int getWidth();
331
int getHeight();
332
}
333
334
class Point {
335
Point(int x, int y);
336
int getX();
337
int getY();
338
Point moveBy(int xOffset, int yOffset);
339
}
340
341
class Rectangle {
342
Rectangle(int x, int y, int width, int height);
343
Rectangle(Point point, Dimension dimension);
344
int getX();
345
int getY();
346
int getWidth();
347
int getHeight();
348
Point getPoint();
349
Dimension getDimension();
350
}
351
```
352
353
### Enumeration Types
354
355
```java { .api }
356
enum Keys {
357
ENTER, TAB, ESCAPE, SPACE, PAGE_UP, PAGE_DOWN, END, HOME,
358
ARROW_LEFT, ARROW_UP, ARROW_RIGHT, ARROW_DOWN,
359
INSERT, DELETE, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,
360
ALT, CONTROL, SHIFT, META, COMMAND, // ... more keys
361
}
362
363
enum Platform {
364
WINDOWS, MAC, LINUX, ANDROID, IOS, UNIX, VISTA, XP, WIN10, WIN11;
365
boolean is(Platform compareWith);
366
static Platform getCurrent();
367
}
368
369
enum OutputType {
370
BASE64, BYTES, FILE;
371
}
372
373
enum PageLoadStrategy {
374
NORMAL, EAGER, NONE;
375
}
376
377
enum WindowType {
378
TAB, WINDOW;
379
}
380
```
381
382
### Exception Hierarchy
383
384
```java { .api }
385
class WebDriverException extends RuntimeException {
386
WebDriverException();
387
WebDriverException(String message);
388
WebDriverException(String message, Throwable cause);
389
String getSystemInformation();
390
String getSupportUrl();
391
String getDriverName();
392
BuildInfo getBuildInformation();
393
}
394
395
// Element-related exceptions
396
class NoSuchElementException extends WebDriverException { }
397
class StaleElementReferenceException extends WebDriverException { }
398
class ElementNotInteractableException extends WebDriverException { }
399
class ElementClickInterceptedException extends WebDriverException { }
400
401
// Navigation exceptions
402
class NoSuchWindowException extends WebDriverException { }
403
class NoSuchFrameException extends WebDriverException { }
404
class NoSuchContextException extends WebDriverException { }
405
406
// Session exceptions
407
class NoSuchSessionException extends WebDriverException { }
408
class SessionNotCreatedException extends WebDriverException { }
409
410
// Timeout exceptions
411
class TimeoutException extends WebDriverException { }
412
class ScriptTimeoutException extends WebDriverException { }
413
414
// Alert exceptions
415
class NoAlertPresentException extends WebDriverException { }
416
class UnhandledAlertException extends WebDriverException { }
417
418
// Validation exceptions
419
class InvalidSelectorException extends WebDriverException { }
420
class InvalidElementStateException extends WebDriverException { }
421
class InvalidArgumentException extends WebDriverException { }
422
```