0
# Selenium Support
1

2
Selenium Support is a comprehensive Java utility library that extends the core Selenium WebDriver functionality with higher-level abstractions and convenience utilities. It provides essential support classes including the Page Object Model pattern implementation, robust waiting mechanisms, event-driven programming support, and UI utilities that significantly reduce boilerplate code and improve test maintainability.
3

4
## Package Information
5

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

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

20
## Core Imports
21

22
```java
23
import org.openqa.selenium.support.PageFactory;
24
import org.openqa.selenium.support.FindBy;
25
import org.openqa.selenium.support.ThreadGuard;
26
import org.openqa.selenium.support.ui.WebDriverWait;
27
import org.openqa.selenium.support.ui.ExpectedConditions;
28
import org.openqa.selenium.support.ui.Select;
29
import org.openqa.selenium.support.ui.LoadableComponent;
30
import org.openqa.selenium.support.events.EventFiringWebDriver;
31
```
32

33
## Basic Usage
34

35
```java
36
import org.openqa.selenium.WebDriver;
37
import org.openqa.selenium.WebElement;
38
import org.openqa.selenium.chrome.ChromeDriver;
39
import org.openqa.selenium.support.FindBy;
40
import org.openqa.selenium.support.PageFactory;
41
import org.openqa.selenium.support.ui.WebDriverWait;
42
import org.openqa.selenium.support.ui.ExpectedConditions;
43
import org.openqa.selenium.support.ui.Select;
44

45
// Page Object Model example
46
public class LoginPage {
47
    @FindBy(id = "username")
48
    private WebElement usernameField;
49
    
50
    @FindBy(id = "password") 
51
    private WebElement passwordField;
52
    
53
    @FindBy(id = "submit")
54
    private WebElement submitButton;
55
    
56
    public LoginPage(WebDriver driver) {
57
        PageFactory.initElements(driver, this);
58
    }
59
    
60
    public void login(String username, String password) {
61
        usernameField.sendKeys(username);
62
        passwordField.sendKeys(password);
63
        submitButton.click();
64
    }
65
}
66

67
// Usage with waits and utilities
68
WebDriver driver = new ChromeDriver();
69
WebDriverWait wait = new WebDriverWait(driver, 10);
70

71
// Initialize page object
72
LoginPage loginPage = new LoginPage(driver);
73

74
// Wait for element and interact
75
WebElement dropdown = wait.until(ExpectedConditions.presenceOfElementLocated(By.id("country")));
76
Select select = new Select(dropdown);
77
select.selectByVisibleText("United States");
78
```
79

80
## Architecture
81

82
The selenium-support library is organized into several key packages:
83

84
- **Core Support** (`org.openqa.selenium.support`): Page Object annotations, utilities, and basic locators
85
- **Page Factory** (`org.openqa.selenium.support.pagefactory`): Element locators, decorators, and Page Object infrastructure  
86
- **UI Utilities** (`org.openqa.selenium.support.ui`): Waiting mechanisms, dropdown helpers, and expected conditions
87
- **Events** (`org.openqa.selenium.support.events`): Event-driven WebDriver wrappers and listener interfaces
88

89
## Capabilities
90

91
### Page Object Model Support
92

93
Provides annotations and factory methods for implementing the Page Object Model pattern with automatic element initialization and flexible locator strategies.
94

95
```java { .api }
96
public class PageFactory {
97
    public static <T> T initElements(WebDriver driver, Class<T> pageClassToProxy);
98
    public static void initElements(WebDriver driver, Object page);
99
    public static void initElements(ElementLocatorFactory factory, Object page);
100
    public static void initElements(FieldDecorator decorator, Object page);
101
}
102

103
@Retention(RetentionPolicy.RUNTIME)
104
@Target({ElementType.FIELD, ElementType.TYPE})
105
public @interface FindBy {
106
    How how() default How.UNSET;
107
    String using() default "";
108
    String id() default "";
109
    String name() default "";
110
    String className() default "";
111
    String css() default "";
112
    String tagName() default "";
113
    String linkText() default "";
114
    String partialLinkText() default "";
115
    String xpath() default "";
116
}
117
```
118

119
[Page Object Factory](./pagefactory.md)
120

121
### Robust Waiting Mechanisms
122

123
Comprehensive waiting utilities for handling dynamic web content with configurable timeouts, polling intervals, and expected conditions.
124

125
```java { .api }
126
public class WebDriverWait extends FluentWait<WebDriver> {
127
    public WebDriverWait(WebDriver driver, long timeOutInSeconds);
128
    public WebDriverWait(WebDriver driver, long timeOutInSeconds, long sleepInMillis);
129
}
130

131
public class FluentWait<T> implements Wait<T> {
132
    public FluentWait<T> withTimeout(Duration timeout);
133
    public FluentWait<T> pollingEvery(Duration interval);
134
    public FluentWait<T> ignoring(Class<? extends Throwable> exceptionType);
135
    public <V> V until(Function<? super T, V> isTrue);
136
}
137

138
public class ExpectedConditions {
139
    public static ExpectedCondition<WebElement> presenceOfElementLocated(By locator);
140
    public static ExpectedCondition<WebElement> visibilityOfElementLocated(By locator);
141
    public static ExpectedCondition<WebElement> elementToBeClickable(By locator);
142
    public static ExpectedCondition<Boolean> titleIs(String title);
143
}
144
```
145

146
[Waiting and Expected Conditions](./waiting.md)
147

148
### Event-Driven WebDriver
149

150
Event firing capabilities for monitoring and logging WebDriver actions with customizable listener interfaces.
151

152
```java { .api }
153
public class EventFiringWebDriver implements WebDriver {
154
    public EventFiringWebDriver(WebDriver driver);
155
    public EventFiringWebDriver register(WebDriverEventListener eventListener);
156
    public EventFiringWebDriver unregister(WebDriverEventListener eventListener);
157
}
158

159
public interface WebDriverEventListener {
160
    void beforeNavigateTo(String url, WebDriver driver);
161
    void afterNavigateTo(String url, WebDriver driver);
162
    void beforeClickOn(WebElement element, WebDriver driver);
163
    void afterClickOn(WebElement element, WebDriver driver);
164
    void onException(Throwable throwable, WebDriver driver);
165
}
166
```
167

168
[Event Handling](./events.md)
169

170
### UI Utilities and Helpers
171

172
Specialized utilities for common web interactions including dropdown selections, color handling, thread safety, component loading, and element locating strategies.
173

174
```java { .api }
175
public class Select implements ISelect {
176
    public Select(WebElement element);
177
    public void selectByVisibleText(String text);
178
    public void selectByIndex(int index);
179
    public void selectByValue(String value);
180
    public List<WebElement> getOptions();
181
    public boolean isMultiple();
182
}
183

184
public class ThreadGuard {
185
    public static WebDriver protect(WebDriver actualWebDriver);
186
}
187

188
public abstract class LoadableComponent<T extends LoadableComponent<T>> {
189
    public T get();
190
    protected abstract void isLoaded() throws Error;
191
    protected abstract void load();
192
}
193

194
public class Color {
195
    public Color(int red, int green, int blue, double alpha);
196
    public static Color fromString(String value);
197
    public String asRgb();
198
    public String asHex();
199
}
200

201
public class ByIdOrName extends By {
202
    public ByIdOrName(String idOrName);
203
}
204
```
205

206
[Utilities and Helpers](./utilities.md)
207

208
## Types
209

210
```java { .api }
211
public interface Wait<F> {
212
    <T> T until(Function<? super F, T> isTrue);
213
}
214

215
public interface ExpectedCondition<T> extends Function<WebDriver, T> {
216
}
217

218
public enum How {
219
    CLASS_NAME, CSS, ID, ID_OR_NAME, LINK_TEXT, NAME, PARTIAL_LINK_TEXT, TAG_NAME, XPATH, UNSET;
220
    public abstract By buildBy(String value);
221
}
222

223
@Retention(RetentionPolicy.RUNTIME)
224
@Target(ElementType.FIELD)
225
public @interface CacheLookup {
226
}
227

228
public interface ISelect {
229
    boolean isMultiple();
230
    List<WebElement> getOptions();
231
    List<WebElement> getAllSelectedOptions();
232
    WebElement getFirstSelectedOption();
233
    void selectByVisibleText(String text);
234
    void selectByIndex(int index);
235
    void selectByValue(String value);
236
}
237
```