0
# Selenium Grid
1

2
Selenium Grid is a distributed testing infrastructure that enables running WebDriver tests in parallel across multiple machines and browsers. It provides a scalable solution for automating web browser testing with centralized session management, load balancing, and support for multiple browser types.
3

4
## Package Information
5

6
- **Package Name**: selenium-grid
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to Maven `pom.xml`:
10
  ```xml
11
  <dependency>
12
    <groupId>org.seleniumhq.selenium</groupId>
13
    <artifactId>selenium-grid</artifactId>
14
    <version>4.33.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.openqa.selenium.grid.Main;
22
import org.openqa.selenium.grid.config.Config;
23
import org.openqa.selenium.grid.config.MemoizedConfig;
24
import org.openqa.selenium.grid.config.MapConfig;
25
import org.openqa.selenium.grid.distributor.Distributor;
26
import org.openqa.selenium.grid.distributor.local.LocalDistributor;
27
import org.openqa.selenium.grid.node.Node;
28
import org.openqa.selenium.grid.node.local.LocalNode;
29
import org.openqa.selenium.grid.router.Router;
30
import org.openqa.selenium.grid.sessionmap.SessionMap;
31
import org.openqa.selenium.grid.sessionmap.local.LocalSessionMap;
32
import org.openqa.selenium.grid.sessionqueue.NewSessionQueue;
33
import org.openqa.selenium.grid.sessionqueue.local.LocalNewSessionQueue;
34
import org.openqa.selenium.events.EventBus;
35
import org.openqa.selenium.remote.tracing.Tracer;
36
```
37

38
## Basic Usage
39

40
```java
41
import org.openqa.selenium.grid.config.Config;
42
import org.openqa.selenium.grid.config.MemoizedConfig;
43
import org.openqa.selenium.grid.config.MapConfig;
44
import org.openqa.selenium.grid.distributor.local.LocalDistributor;
45
import org.openqa.selenium.grid.node.local.LocalNode;
46
import org.openqa.selenium.grid.sessionmap.local.LocalSessionMap;
47
import org.openqa.selenium.grid.sessionqueue.local.LocalNewSessionQueue;
48
import org.openqa.selenium.events.EventBus;
49
import org.openqa.selenium.remote.tracing.Tracer;
50
import org.openqa.selenium.grid.security.Secret;
51

52
import java.net.URI;
53
import java.time.Duration;
54
import java.util.Map;
55

56
// Create basic configuration
57
Config config = new MemoizedConfig(new MapConfig(Map.of()));
58

59
// Create required dependencies
60
Tracer tracer = Tracer.builder().build();
61
EventBus eventBus = EventBus.builder().build();
62
Secret registrationSecret = new Secret("secret");
63

64
// Create grid components
65
SessionMap sessionMap = new LocalSessionMap(tracer, eventBus);
66
NewSessionQueue sessionQueue = new LocalNewSessionQueue(
67
    tracer, 
68
    slotMatcher,
69
    Duration.ofSeconds(300),
70
    Duration.ofSeconds(300),
71
    Duration.ofSeconds(5),
72
    registrationSecret,
73
    10
74
);
75

76
LocalDistributor distributor = new LocalDistributor(
77
    tracer,
78
    eventBus,
79
    httpClientFactory,
80
    sessionMap,
81
    sessionQueue,
82
    slotSelector,
83
    registrationSecret,
84
    Duration.ofSeconds(120),
85
    false,
86
    Duration.ofSeconds(5),
87
    4,
88
    slotMatcher,
89
    Duration.ofMinutes(5)
90
);
91

92
// Register node with distributor
93
distributor.add(node);
94
```
95

96
## Architecture
97

98
Selenium Grid uses a modular, distributed architecture consisting of:
99

100
- **Router**: Entry point that receives WebDriver requests and routes them to appropriate components
101
- **Distributor**: Manages node registration and session creation, distributing work across available nodes
102
- **Session Map**: Tracks active sessions and their locations across the grid
103
- **Session Queue**: Manages incoming session requests when nodes are busy
104
- **Node**: Executes WebDriver commands and manages browser sessions
105
- **Event Bus**: Provides asynchronous communication between components
106

107
Components can run in the same process (Standalone mode) or distributed across multiple machines (Hub and Node mode).
108

109
## Capabilities
110

111
### Configuration Management
112

113
Flexible configuration system supporting multiple sources (files, environment variables, command-line flags) with role-based configuration and type-safe access.
114

115
```java { .api }
116
interface Config {
117
    Set<String> getSectionNames();
118
    Set<String> getOptions(String section);
119
    Optional<String> get(String section, String option);
120
    Optional<Integer> getInt(String section, String option);
121
    Optional<Boolean> getBool(String section, String option);
122
    <X> X getClass(String section, String option, Class<X> typeOfClass, String defaultClazz);
123
}
124

125
class Role implements Comparable<Role> {
126
    Role(String roleName);
127
    static Role of(String name);
128
    String getRoleName();
129
}
130
```
131

132
[Configuration System](./configuration.md)
133

134
### Session Distribution
135

136
Core session management and distribution across grid nodes with load balancing, capacity management, and slot selection strategies.
137

138
```java { .api }
139
abstract class Distributor {
140
    protected Distributor(Tracer tracer, HttpClient.Factory httpClientFactory, Secret registrationSecret);
141
    abstract Either<SessionNotCreatedException, CreateSessionResponse> newSession(SessionRequest request);
142
    abstract Distributor add(Node node);
143
    abstract boolean drain(NodeId nodeId);
144
    abstract void remove(NodeId nodeId);
145
    abstract DistributorStatus getStatus();
146
}
147

148
@FunctionalInterface
149
interface SlotSelector {
150
    Set<SlotId> selectSlot(Capabilities capabilities, Set<NodeStatus> nodes, SlotMatcher slotMatcher);
151
}
152
```
153

154
[Session Distribution](./session-distribution.md)
155

156
### Node Management
157

158
WebDriver session execution and browser lifecycle management with support for local and remote execution, Docker integration, and health monitoring.
159

160
```java { .api }
161
abstract class Node {
162
    protected Node(Tracer tracer, NodeId id, URI uri, Secret registrationSecret, Duration sessionTimeout);
163
    abstract Either<WebDriverException, CreateSessionResponse> newSession(CreateSessionRequest sessionRequest);
164
    abstract HttpResponse executeWebDriverCommand(HttpRequest req);
165
    abstract Session getSession(SessionId id);
166
    abstract void stop(SessionId id);
167
    abstract boolean isSessionOwner(SessionId id);
168
    abstract boolean isSupporting(Capabilities capabilities);
169
    abstract NodeStatus getStatus();
170
    abstract HealthCheck getHealthCheck();
171
    abstract void drain();
172
    NodeId getId();
173
    URI getUri();
174
}
175
```
176

177
[Node Management](./node-management.md)
178

179
### Request Routing
180

181
HTTP request routing and WebDriver command processing with session resolution, WebSocket proxying, and status endpoints.
182

183
```java { .api }
184
class Router {
185
    Router(Tracer tracer, HttpClient.Factory clientFactory, SessionMap sessions, 
186
           NewSessionQueue queue, Distributor distributor);
187
    boolean isReady();
188
    boolean matches(HttpRequest req);
189
    HttpResponse execute(HttpRequest req);
190
    void close();
191
}
192
```
193

194
[Request Routing](./request-routing.md)
195

196
### Session Storage
197

198
Persistent session mapping and storage with support for in-memory, JDBC, and Redis backends for tracking active sessions across the grid.
199

200
```java { .api }
201
interface SessionMap {
202
    boolean isReady();
203
    boolean add(Session session);
204
    Session get(SessionId id);
205
    void remove(SessionId id);
206
    Set<Session> getSessions();
207
}
208
```
209

210
[Session Storage](./session-storage.md)
211

212
### Session Queuing
213

214
Request queuing system for managing session creation requests when nodes are at capacity, with timeout handling and prioritization.
215

216
```java { .api }
217
interface NewSessionQueue {
218
    boolean isReady();
219
    boolean offerLast(SessionRequest request, RequestId requestId);
220
    Optional<SessionRequest> poll(Duration timeout);
221
    int clear();
222
    List<SessionRequest> getNextAvailable(Map<Capabilities, Long> stereotypes);
223
}
224
```
225

226
[Session Queuing](./session-queuing.md)
227

228
### Security Features
229

230
Authentication and authorization framework with secret management, basic authentication, and request filtering for securing grid endpoints.
231

232
```java { .api }
233
class Secret {
234
    // Implementation hidden for security
235
}
236

237
class BasicAuthenticationFilter implements Filter {
238
    // HTTP Basic Authentication implementation
239
}
240

241
class RequiresSecretFilter implements Filter {
242
    // Secret validation filter
243
}
244
```
245

246
[Security Features](./security.md)
247

248
### CLI Commands
249

250
Command-line interface for starting and managing grid components with configuration support and help system.
251

252
```java { .api }
253
class Main {
254
    public static void main(String[] args);
255
}
256

257
@AutoService(CliCommand.class)
258
class Hub extends TemplateGridServerCommand {
259
    String getName();
260
    Set<Role> getConfigurableRoles();
261
    Set<Object> getFlagObjects();
262
    Config getDefaultConfig();
263
    Handlers<Route> createHandlers(Config config);
264
}
265
```
266

267
[CLI Commands](./cli-commands.md)
268

269
## Types
270

271
```java { .api }
272
class Session {
273
    Session(SessionId id, URI uri, Capabilities stereotype, Capabilities capabilities, Instant startTime);
274
    SessionId getId();
275
    URI getUri();
276
    Capabilities getStereotype();
277
    Capabilities getCapabilities();
278
    Instant getStartTime();
279
}
280

281
class NodeStatus {
282
    NodeStatus(NodeId nodeId, URI externalUri, int maxSessionCount, Set<Slot> slots, 
283
               Availability availability, Duration heartbeatPeriod, Duration sessionTimeout, 
284
               String version, Map<String, String> osInfo);
285
    boolean hasCapability(Capabilities caps, SlotMatcher slotMatcher);
286
    boolean hasCapacity();
287
    boolean hasCapacity(Capabilities caps, SlotMatcher slotMatcher);
288
    NodeId getNodeId();
289
    URI getExternalUri();
290
    Set<Slot> getSlots();
291
    Availability getAvailability();
292
    float getLoad();
293
}
294

295
class Slot {
296
    Slot(SlotId id, Capabilities stereotype, Instant lastStarted, Session session);
297
    SlotId getId();
298
    Capabilities getStereotype();
299
    Session getSession();
300
    boolean isSupporting(Capabilities caps, SlotMatcher slotMatcher);
301
}
302

303
enum Availability {
304
    UP, DOWN, DRAINING
305
}
306

307
// Typed identifiers
308
class NodeId { /* UUID-based implementation */ }
309
class SlotId { /* UUID-based implementation */ }  
310
class SessionId { /* UUID-based implementation */ }
311
class RequestId { /* UUID-based implementation */ }
312
```