or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

alerts.mdconfiguration.mddrivers.mdelements.mdindex.mdinteractions.mdjavascript.mdlocators.mdpage-objects.mdwaits.mdwebdriver.md
tile.json

tessl/maven-org-seleniumhq-selenium--selenium-api

Selenium WebDriver core API for automating web browsers across different platforms and programming languages.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.seleniumhq.selenium/selenium-api@4.33.x

To install, run

npx @tessl/cli install tessl/maven-org-seleniumhq-selenium--selenium-api@4.33.0

index.mddocs/

Selenium WebDriver API

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.

Package Information

  • Package Name: org.seleniumhq.selenium:selenium-api
  • Package Type: maven
  • Language: Java
  • Installation: Add dependency to pom.xml:
<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>4.33.0</version>
</dependency>

Or to build.gradle:

implementation 'org.seleniumhq.selenium:selenium-java:4.33.0'

Core Imports

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.By;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ui.WebDriverWait;
import org.openqa.selenium.support.ui.ExpectedConditions;

Basic Usage

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.By;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ui.WebDriverWait;
import org.openqa.selenium.support.ui.ExpectedConditions;
import java.time.Duration;

// Create a new browser instance
WebDriver driver = new ChromeDriver();

try {
    // Navigate to a website
    driver.get("https://example.com");
    
    // Find element and interact with it
    WebElement searchBox = driver.findElement(By.name("q"));
    searchBox.sendKeys("selenium webdriver");
    searchBox.submit();
    
    // Wait for and verify results
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    WebElement results = wait.until(
        ExpectedConditions.presenceOfElementLocated(By.id("results"))
    );
    
    System.out.println("Page title: " + driver.getTitle());
} finally {
    // Always close the browser
    driver.quit();
}

Architecture

Selenium WebDriver API is built around several key components:

  • WebDriver Interface: Main browser control interface providing navigation, element finding, and window management
  • WebElement Interface: HTML element interaction interface for clicking, typing, and querying element properties
  • Element Locators: By class providing various strategies to locate elements (ID, XPath, CSS selectors, etc.)
  • Browser Drivers: Browser-specific implementations (ChromeDriver, FirefoxDriver, EdgeDriver, SafariDriver)
  • Support Utilities: Higher-level utilities like explicit waits, page object support, and complex user interactions
  • Capabilities System: Configuration management for browser options, proxies, and platform-specific settings

Capabilities

Core WebDriver Interface

Primary interface for browser automation providing navigation, element finding, window management, and session control.

interface WebDriver extends SearchContext {
    void get(String url);
    String getCurrentUrl();
    String getTitle();
    String getPageSource();
    void quit();
    void close();
    Set<String> getWindowHandles();
    String getWindowHandle();
    TargetLocator switchTo();
    Navigation navigate();
    Options manage();
}

Core WebDriver

Element Interaction

Comprehensive interface for interacting with HTML elements including clicking, typing, querying properties, and taking screenshots.

interface WebElement extends SearchContext, TakesScreenshot {
    void click();
    void submit();
    void sendKeys(CharSequence... keysToSend);
    void clear();
    String getTagName();
    String getDomAttribute(String name);
    String getDomProperty(String name);
    String getAttribute(String name);
    String getAriaRole();
    String getAccessibleName();
    boolean isSelected();
    boolean isEnabled();
    boolean isDisplayed();
    String getText();
    String getCssValue(String propertyName);
    Point getLocation();
    Dimension getSize();
    Rectangle getRect();
}

Element Interaction

Element Location Strategies

Factory class providing various strategies to locate elements in the DOM including ID, XPath, CSS selectors, text-based searches, and modern spatial locators.

abstract class By {
    static By id(String id);
    static By name(String name);
    static By className(String className);
    static By tagName(String tagName);
    static By xpath(String xpathExpression);
    static By cssSelector(String cssSelector);
    static By linkText(String linkText);
    static By partialLinkText(String partialLinkText);
}

class RelativeLocator {
    static RelativeBy with(By by);
}

Element Location

Browser Configuration

Comprehensive capability system for configuring browser options, proxy settings, platform preferences, and authentication.

interface Capabilities {
    String getBrowserName();
    String getBrowserVersion();
    Platform getPlatform();
    String getPlatformName();
    Object getCapability(String capabilityName);
    Set<String> getCapabilityNames();
    Map<String, Object> asMap();
}

class MutableCapabilities implements Capabilities {
    MutableCapabilities setCapability(String name, Object value);
    MutableCapabilities merge(Capabilities other);
}

Browser Configuration

Explicit Waits and Conditions

Sophisticated waiting mechanisms for handling dynamic content, with pre-built conditions and custom wait logic support.

class WebDriverWait extends FluentWait<WebDriver> {
    WebDriverWait(WebDriver driver, Duration timeout);
    <V> V until(Function<WebDriver, V> isTrue);
    <V> V until(ExpectedCondition<V> condition);
}

class ExpectedConditions {
    static ExpectedCondition<WebElement> presenceOfElementLocated(By locator);
    static ExpectedCondition<WebElement> visibilityOfElementLocated(By locator);
    static ExpectedCondition<WebElement> elementToBeClickable(By locator);
    static ExpectedCondition<Boolean> textToBePresentInElement(WebElement element, String text);
    static ExpectedCondition<Boolean> titleIs(String title);
    static ExpectedCondition<Alert> alertIsPresent();
}

Waits and Conditions

Complex User Interactions

Advanced interaction capabilities including mouse actions, keyboard input, drag-and-drop operations, and action chaining.

class Actions {
    Actions(WebDriver driver);
    Actions click();
    Actions click(WebElement target);
    Actions doubleClick();
    Actions doubleClick(WebElement target);
    Actions contextClick();
    Actions contextClick(WebElement target);
    Actions dragAndDrop(WebElement source, WebElement target);
    Actions dragAndDropBy(WebElement source, int xOffset, int yOffset);
    Actions keyDown(Keys key);
    Actions keyUp(Keys key);
    Actions sendKeys(CharSequence... keys);
    Actions moveToElement(WebElement target);
    Actions moveByOffset(int xOffset, int yOffset);
    Actions pause(Duration duration);
    void perform();
}

User Interactions

Browser-Specific Drivers

Concrete WebDriver implementations for major browsers with browser-specific configuration options and capabilities.

class ChromeDriver implements WebDriver, JavascriptExecutor, TakesScreenshot, HasAuthentication, HasBiDi, HasDevTools {
    ChromeDriver();
    ChromeDriver(ChromeOptions options);
}

class ChromeOptions extends MutableCapabilities {
    ChromeOptions addArguments(String... arguments);
    ChromeOptions addArguments(List<String> arguments);
    ChromeOptions addExtensions(File... paths);
    ChromeOptions setExperimentalOption(String name, Object value);
    ChromeOptions setHeadless(boolean headless);
    ChromeOptions setBinary(String path);
}

Browser Drivers

Page Object Model Support

Utilities for implementing the Page Object Model pattern including element initialization, locator annotations, and event handling.

class PageFactory {
    static void initElements(WebDriver driver, Object page);
    static void initElements(ElementLocatorFactory factory, Object page);
}

@interface FindBy {
    String id() default "";
    String name() default "";
    String className() default "";
    String tagName() default "";
    String xpath() default "";
    String css() default "";
    String linkText() default "";
    String partialLinkText() default "";
}

Page Object Model

JavaScript Execution

Interface for executing JavaScript code in the browser context with support for synchronous/asynchronous execution and script pinning.

interface JavascriptExecutor {
    Object executeScript(String script, Object... args);
    Object executeAsyncScript(String script, Object... args);
    ScriptKey pin(String script);
    void unpin(ScriptKey key);
    Set<ScriptKey> getPinnedScripts();
    Object executeScript(ScriptKey key, Object... args);
}

JavaScript Execution

Alert and Dialog Handling

Interface for interacting with JavaScript alerts, prompts, and confirmation dialogs.

interface Alert {
    void dismiss();
    void accept();
    String getText();
    void sendKeys(String keysToSend);
}

Alert Handling

Core Types

Common Data Types

class Cookie {
    Cookie(String name, String value);
    Cookie(String name, String value, String domain, String path, Date expiry, boolean isSecure, boolean isHttpOnly, String sameSite);
    String getName();
    String getValue();
    String getDomain();
    String getPath();
    Date getExpiry();
    boolean isSecure();
    boolean isHttpOnly();
    String getSameSite();
}

class Dimension {
    Dimension(int width, int height);
    int getWidth();
    int getHeight();
}

class Point {
    Point(int x, int y);
    int getX();
    int getY();
    Point moveBy(int xOffset, int yOffset);
}

class Rectangle {
    Rectangle(int x, int y, int width, int height);
    Rectangle(Point point, Dimension dimension);
    int getX();
    int getY();
    int getWidth();
    int getHeight();
    Point getPoint();
    Dimension getDimension();
}

Enumeration Types

enum Keys {
    ENTER, TAB, ESCAPE, SPACE, PAGE_UP, PAGE_DOWN, END, HOME,
    ARROW_LEFT, ARROW_UP, ARROW_RIGHT, ARROW_DOWN,
    INSERT, DELETE, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12,
    ALT, CONTROL, SHIFT, META, COMMAND, // ... more keys
}

enum Platform {
    WINDOWS, MAC, LINUX, ANDROID, IOS, UNIX, VISTA, XP, WIN10, WIN11;
    boolean is(Platform compareWith);
    static Platform getCurrent();
}

enum OutputType {
    BASE64, BYTES, FILE;
}

enum PageLoadStrategy {
    NORMAL, EAGER, NONE;
}

enum WindowType {
    TAB, WINDOW;
}

Exception Hierarchy

class WebDriverException extends RuntimeException {
    WebDriverException();
    WebDriverException(String message);
    WebDriverException(String message, Throwable cause);
    String getSystemInformation();
    String getSupportUrl();
    String getDriverName();
    BuildInfo getBuildInformation();
}

// Element-related exceptions
class NoSuchElementException extends WebDriverException { }
class StaleElementReferenceException extends WebDriverException { }
class ElementNotInteractableException extends WebDriverException { }
class ElementClickInterceptedException extends WebDriverException { }

// Navigation exceptions
class NoSuchWindowException extends WebDriverException { }
class NoSuchFrameException extends WebDriverException { }
class NoSuchContextException extends WebDriverException { }

// Session exceptions
class NoSuchSessionException extends WebDriverException { }
class SessionNotCreatedException extends WebDriverException { }

// Timeout exceptions
class TimeoutException extends WebDriverException { }
class ScriptTimeoutException extends WebDriverException { }

// Alert exceptions
class NoAlertPresentException extends WebDriverException { }
class UnhandledAlertException extends WebDriverException { }

// Validation exceptions
class InvalidSelectorException extends WebDriverException { }
class InvalidElementStateException extends WebDriverException { }
class InvalidArgumentException extends WebDriverException { }