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
```