0
# Testcontainers Selenium
1

2
Testcontainers Selenium provides Selenium WebDriver container support for automated testing with web browsers running in Docker containers. It offers containerized instances of Chrome, Firefox, and Edge browsers, providing a clean, isolated browser environment for each test run with features like video recording, VNC access, and automatic browser version compatibility.
3

4
## Package Information
5

6
- **Package Name**: org.testcontainers:selenium
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>org.testcontainers</groupId>
13
      <artifactId>testcontainers</artifactId>
14
      <version>1.21.3</version>
15
  </dependency>
16
  <dependency>
17
      <groupId>org.testcontainers</groupId>
18
      <artifactId>selenium</artifactId>
19
      <version>1.21.3</version>
20
  </dependency>
21
  ```
22

23
## Core Imports
24

25
```java
26
import org.testcontainers.containers.BrowserWebDriverContainer;
27
import org.testcontainers.utility.DockerImageName;
28
import org.openqa.selenium.Capabilities;
29
import org.openqa.selenium.chrome.ChromeOptions;
30
import org.openqa.selenium.firefox.FirefoxOptions;
31
import org.openqa.selenium.edge.EdgeOptions;
32
import org.openqa.selenium.remote.RemoteWebDriver;
33
import java.net.URL;
34
```
35

36
## Basic Usage
37

38
```java
39
import org.testcontainers.containers.BrowserWebDriverContainer;
40
import org.openqa.selenium.chrome.ChromeOptions;
41
import org.openqa.selenium.remote.RemoteWebDriver;
42

43
// Create a Chrome browser container
44
BrowserWebDriverContainer<?> chrome = new BrowserWebDriverContainer<>()
45
    .withCapabilities(new ChromeOptions());
46

47
// Start the container
48
chrome.start();
49

50
// Get the Selenium endpoint URL
51
URL seleniumAddress = chrome.getSeleniumAddress();
52

53
// Create RemoteWebDriver instance
54
RemoteWebDriver driver = new RemoteWebDriver(seleniumAddress, new ChromeOptions());
55

56
// Use the driver for testing
57
driver.get("https://example.com");
58

59
// Clean up
60
driver.quit();
61
chrome.stop();
62
```
63

64
## Architecture
65

66
The Selenium module is built around the `BrowserWebDriverContainer` class which extends the core Testcontainers `GenericContainer`. Key components include:
67

68
- **BrowserWebDriverContainer**: Main container class for browser automation
69
- **Video Recording**: VNC-based session recording with configurable modes
70
- **Browser Support**: Chrome, Firefox, and Edge containers from SeleniumHQ
71
- **Version Compatibility**: Automatic browser version selection based on Selenium API version
72

73
## Capabilities
74

75
### [Browser Container Management](./browser-container.md)
76

77
Core functionality for creating and configuring Selenium browser containers with different browsers, capabilities, and Docker images.
78

79
**Key APIs:**
80
```java { .api }
81
public BrowserWebDriverContainer();
82
public BrowserWebDriverContainer(String dockerImageName);
83
public BrowserWebDriverContainer(DockerImageName dockerImageName);
84
public SELF withCapabilities(Capabilities capabilities);
85
public URL getSeleniumAddress();
86
public String getVncAddress();
87
```
88

89
### [Video Recording](./video-recording.md)
90

91
Video recording capabilities for test sessions using VNC recording with configurable modes and file naming.
92

93
**Key APIs:**
94
```java { .api }
95
public SELF withRecordingMode(VncRecordingMode recordingMode, File vncRecordingDirectory);
96
public SELF withRecordingMode(VncRecordingMode recordingMode, File vncRecordingDirectory, VncRecordingFormat recordingFormat);
97
public SELF withRecordingFileFactory(RecordingFileFactory recordingFileFactory);
98
```
99

100
### [Selenium Version Detection](./selenium-utils.md)
101

102
Utilities for detecting Selenium version from classpath and ensuring browser image compatibility.
103

104
**Key APIs:**
105
```java { .api }
106
public static String determineClasspathSeleniumVersion();
107
public static String getSeleniumVersionFromManifest(Manifest manifest);
108
```
109

110
## Types
111

112
### VncRecordingMode
113

114
```java { .api }
115
public enum VncRecordingMode {
116
    SKIP,
117
    RECORD_ALL,
118
    RECORD_FAILING
119
}
120
```
121

122
### VncRecordingFormat
123

124
```java { .api }
125
public enum VncRecordingFormat {
126
    FLV("flv"),
127
    MP4("mp4");
128
    
129
    public String getFilenameExtension();
130
}
131
```
132

133
### RecordingFileFactory
134

135
```java { .api }
136
public interface RecordingFileFactory {
137
    File recordingFileForTest(File vncRecordingDirectory, String prefix, boolean succeeded);
138
    default File recordingFileForTest(
139
        File vncRecordingDirectory, 
140
        String prefix, 
141
        boolean succeeded, 
142
        VncRecordingFormat recordingFormat
143
    );
144
}
145
```
146

147
### Constants
148

149
```java { .api }
150
public static final String DEFAULT_SELENIUM_VERSION = "2.45.0";
151
```