Selenium Deployment and Usage Guide

This guide provides instructions for deploying and using the Selenium browser automation framework.

Prerequisites

To set up a local development environment for Selenium, you will need the following:

All Platforms

Bazelisk: A Bazel wrapper that automatically downloads the correct Bazel version.
- Installation instructions: Bazelisk GitHub
Java Development Kit (JDK): Version 17 or greater (e.g., Java 17 Temurin).
- Ensure JAVA_HOME environment variable is set to the JDK installation directory.
- Verify installation by running javac in your terminal.

MacOS

Xcode Command-Line Tools:
```
xcode-select --install
```
Rosetta (for Apple Silicon Macs): Add build --host_platform=//:rosetta to your .bazelrc.local file.

Windows

Choose either automatic or manual installation:

Option 1: Automatic Installation (Recommended)

Open PowerShell as an Administrator.

Allow script execution for the current process:

Set-ExecutionPolicy Bypass -Scope Process -Force

Navigate to the directory where you want to clone Selenium (or the parent directory if already cloned).

Download and execute the setup script:

# Assuming you are in the Selenium project root or its parent directory
# If Selenium is not cloned, clone it first: git clone https://github.com/SeleniumHQ/selenium.git
# Then navigate into the selenium directory: cd selenium
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/SeleniumHQ/selenium/trunk/scripts/dev-environment-setup.ps1" -OutFile "dev-environment-setup.ps1"
.\dev-environment-setup.ps1

Option 2: Manual Installation

Allow running scripts in Selenium:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Enable Developer Mode:

reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock" /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"

MSYS2: Install MSYS2.
- Add its bin directory (e.g., C:\tools\msys64\usr\bin) to your system PATH environment variable.
- Set BAZEL_SH environment variable to the bash.exe location (e.g., C:\tools\msys64\usr\bin\bash.exe).
Visual Studio Community: Install the latest version of Visual Studio Community.
- During installation, add the "Desktop development with C++" workload.
- Set BAZEL_VC environment variable to the Visual C++ build tools installation directory (e.g., C:\Program Files\Microsoft Visual Studio\2022\Community\VC).
- Set BAZEL_VC_FULL_VERSION environment variable to the version string found in the directory name within "$BAZEL_VC\Tools\MSVC\".
Long File Paths Support:
- Enable Long Paths:
```
reg add "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Command Processor" /t REG_DWORD /f /v "DisableUNCCheck" /d "1"
reg add "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem" /t REG_DWORD /f /v "LongPathsEnabled" /d "1"
```
- Allow Bazel to create short names for long paths:
```
fsutil 8dot3name set 0
```
- Configure Bazel output to C:/tmp to avoid nested directory issues:
  - Create a file selenium/.bazelrc.windows.local in the project root.
  - Add startup --output_user_root=C:/tmp to this file.

Installation

Clone the Repository:

git clone https://github.com/SeleniumHQ/selenium.git
cd selenium

Verify Prerequisites: Ensure all prerequisites mentioned above are correctly installed and configured. Bazelisk will automatically handle Bazel installation.

Configuration

Selenium's core functionality is configured programmatically within your test scripts. For development and building, Bazel uses .bazelrc files.

Environment Variables:
- JAVA_HOME: Points to your JDK installation.
- BAZEL_SH (Windows): Path to bash.exe from MSYS2.
- BAZEL_VC (Windows): Path to Visual C++ build tools.
- BAZEL_VC_FULL_VERSION (Windows): Version of Visual C++ build tools.
Bazel Configuration:
- .bazelversion: Specifies the Bazel version to be used by Bazelisk.
- .bazelrc.local: (Optional) Local Bazel configuration overrides. For example, on Apple Silicon Macs, add build --host_platform=//:rosetta here.
- selenium/.bazelrc.windows.local: (Windows specific) Used to set Bazel output root to C:/tmp.

Build & Run

Selenium is a comprehensive framework. Building the entire project compiles all components, including the WebDriver implementations, Grid, and various utilities.

Build the Project: Navigate to the root of the cloned Selenium repository and run:
```
bazel build //...
```
This command builds all targets defined in the project. This can take a significant amount of time on the first run.
Running Tests (Development): To run all tests:
```
bazel test //...
```
To run specific tests, for example, tests related to RemoteWebDriver:
```
bazel test //java/src/org/openqa/selenium/remote:remote_driver_tests
```

Running a Specific Component (Example: Selenium Grid): While the primary use case for Selenium is as a library in your test automation projects, you can run components like the Selenium Grid directly.

First, build the Grid server:

bazel build //java/src/org/openqa/selenium/grid/selenium:selenium-grid-dist

The output will be in bazel-bin/java/src/org/openqa/selenium/grid/selenium/selenium-grid-dist.jar.

To run the Grid in standalone mode (for local testing):

java -jar bazel-bin/java/src/org/openqa/selenium/grid/selenium/selenium-grid-dist.jar standalone --port 4444

This will start a Selenium Grid instance accessible at http://localhost:4444.

To use the Grid, you would then configure your RemoteWebDriver instance in your test code to point to this URL:

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.remote.DesiredCapabilities;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;

public class MyTest {
    public static void main(String[] args) throws Exception {
        DesiredCapabilities capabilities = new DesiredCapabilities();
        capabilities.setBrowserName("chrome"); // Or "firefox", etc.

        WebDriver driver = new RemoteWebDriver(new URL("http://localhost:4444"), capabilities);
        driver.get("https://www.selenium.dev");
        System.out.println("Page title: " + driver.getTitle());
        driver.quit();
    }
}

Deployment

Selenium itself is a framework and library, not an application that is typically "deployed" in the traditional sense to a cloud provider. Instead, its components (like Selenium Grid) can be deployed, and the libraries are integrated into your test automation projects.

Integrating Selenium into Your Project

For most users, Selenium is consumed as a dependency in a test project.

Maven: Add the following to your pom.xml:

<dependencies>
    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>4.x.x</version> <!-- Use the latest stable version -->
    </dependency>
</dependencies>

Gradle: Add the following to your build.gradle:

dependencies {
    implementation 'org.seleniumhq.selenium:selenium-java:4.x.x' // Use the latest stable version
}

Deploying Selenium Grid

Selenium Grid allows you to run tests on a distributed network of machines.

Standalone Mode (for simple deployments or local testing)

As shown in the "Build & Run" section, you can run the selenium-grid-dist.jar in standalone mode. This is suitable for small-scale testing or local development.

java -jar selenium-grid-dist.jar standalone --port 4444

Hub and Node Architecture (for larger-scale, distributed testing)

Build the Grid JAR:
```
bazel build //java/src/org/openqa/selenium/grid/selenium:selenium-grid-dist
```
The JAR will be located at bazel-bin/java/src/org/openqa/selenium/grid/selenium/selenium-grid-dist.jar.
Start the Hub: On a central machine, start the Hub:
```
java -jar selenium-grid-dist.jar hub --port 4444
```
The Hub will be available at http://<hub-ip>:4444.
Start Nodes: On machines with browsers installed (Chrome, Firefox, Edge, etc.), start one or more Nodes, registering them with the Hub:
```
java -jar selenium-grid-dist.jar node --port 5555 --hub http://<hub-ip>:4444
```
Replace <hub-ip> with the actual IP address or hostname of the machine running the Hub. Each node should run on a different port if on the same machine, or on the default port (5555) if on different machines.

Containerized Deployment (Docker/Kubernetes)

For robust and scalable deployments, especially in CI/CD pipelines, containerization is highly recommended. Selenium provides official Docker images.

Pull Docker Images:

docker pull selenium/standalone-chrome
docker pull selenium/standalone-firefox
docker pull selenium/hub
docker pull selenium/node-chrome
docker pull selenium/node-firefox

Run Standalone Browser (for quick local tests):
```
docker run -d -p 4444:4444 -p 7900:7900 --shm-size="2g" selenium/standalone-chrome:latest
```
Access at http://localhost:4444. VNC is available on port 7900.

Run Hub and Nodes (Distributed Grid):

Start Hub:

docker run -d -p 4444:4444 --name selenium-hub selenium/hub:latest

Start Chrome Node (linking to Hub):

docker run -d -p 5555:5555 --link selenium-hub:hub --shm-size="2g" selenium/node-chrome:latest

Start Firefox Node (linking to Hub):

docker run -d -p 5556:5555 --link selenium-hub:hub --shm-size="2g" selenium/node-firefox:latest

Your tests would then connect to http://localhost:4444.

For Kubernetes deployments, refer to the official Selenium documentation on deploying with Kubernetes, which often involves Helm charts or custom YAML configurations.

Troubleshooting

JAVA_HOME not set or incorrect:
- Symptom: javac command not found or Bazel build fails with Java-related errors.
- Solution: Ensure JAVA_HOME environment variable points to your JDK installation directory (e.g., C:\Program Files\Java\jdk-17 on Windows, /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home on macOS).
Bazel build failures (Windows):
- Symptom: Errors related to long file paths, C++ compiler not found, or bash.exe issues.
- Solution:
  - Verify MSYS2 installation, BAZEL_SH environment variable.
  - Confirm Visual Studio "Desktop development with C++" workload is installed, and BAZEL_VC, BAZEL_VC_FULL_VERSION are set correctly.
  - Ensure long path support is enabled and selenium/.bazelrc.windows.local exists with startup --output_user_root=C:/tmp.
MacOS xcode-select issues:
- Symptom: Build errors related to command-line tools.
- Solution: Run xcode-select --install and ensure it completes successfully.
Apple Silicon Mac build errors:
- Symptom: Build failures on M1/M2 Macs.
- Solution: Add build --host_platform=//:rosetta to your .bazelrc.local file.
Selenium Grid not registering nodes:
- Symptom: Nodes fail to connect to the Hub, or tests don't find available browsers.
- Solution:
  - Verify network connectivity between Hub and Node machines.
  - Ensure Hub and Node ports are open in firewalls.
  - Double-check the --hub URL provided to the node is correct and accessible from the node machine.
  - Check Hub and Node logs for error messages.
RemoteWebDriver unable to connect:
- Symptom: SessionNotCreatedException or connection refused errors when trying to instantiate RemoteWebDriver.
- Solution:
  - Ensure your Selenium Grid Hub or standalone server is running and accessible at the specified URL and port.
  - Verify the requested capabilities (browser name, version) match what the Grid has available.
  - Check network firewalls.
Outdated Selenium version:
- Symptom: Unexpected behavior, bugs, or incompatibility with newer browser versions.
- Solution: Always use the latest stable version of selenium-java in your project dependencies. Update browser drivers (e.g., ChromeDriver, GeckoDriver) to match your browser and Selenium versions.

How to Deploy & Use SeleniumHQ/selenium