Jenkins Selenium Integration: Running Browser Tests in CI
Jenkins Selenium integration is one of the most common browser testing setups in enterprise QA. This guide covers the complete setup — from configuring Jenkins agents to run headless Chrome, to publishing results and capturing screenshots on failure.
The Jenkins Selenium Challenge
Running Selenium in Jenkins is more involved than running unit tests because browsers need a display environment. On Linux Jenkins agents, there's no graphical display by default — Chrome will refuse to start unless you use headless mode or configure a virtual display (Xvfb).
The three approaches, in order of preference:
- Headless Chrome — simplest, no display required, Chrome 60+
- Xvfb (X Virtual Framebuffer) — virtual display for non-headless scenarios
- Docker with headless Chrome — most consistent, recommended for new setups
Option 1: Headless Chrome in Jenkins
The cleanest approach. Configure your Selenium tests to use headless Chrome and no display setup is needed.
Install Chrome on Jenkins Agent
For Ubuntu/Debian agents:
# Add Google Chrome repo
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | \
sudo tee /etc/apt/sources.list.d/google-chrome.list
# Install Chrome
sudo apt-get update
sudo apt-get install -y google-chrome-stableOr use a shell script step in your Jenkinsfile for the agent setup:
stage('Setup') {
steps {
sh '''
if ! command -v google-chrome &> /dev/null; then
wget -q -O /tmp/chrome.deb https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt-get install -y /tmp/chrome.deb
fi
'''
}
}Configure Selenium for Headless Mode
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
from webdriver_manager.chrome import ChromeDriverManager
import os
def get_driver():
options = Options()
options.add_argument('--headless=new') # Chrome 112+ headless mode
options.add_argument('--no-sandbox')
options.add_argument('--disable-dev-shm-usage')
options.add_argument('--disable-gpu')
options.add_argument('--window-size=1920,1080')
options.add_argument('--disable-extensions')
service = Service(ChromeDriverManager().install())
return webdriver.Chrome(service=service, options=options)--no-sandbox and --disable-dev-shm-usage are required for Chrome in Jenkins environments. Without them, Chrome may crash with cryptic errors.
Jenkinsfile for Headless Selenium
pipeline {
agent any
stages {
stage('Test') {
steps {
sh '''
pip install -r requirements.txt
pytest tests/e2e/ \
--junitxml=selenium-results.xml \
-v \
--tb=long
'''
}
post {
always {
junit 'selenium-results.xml'
archiveArtifacts artifacts: 'screenshots/**', allowEmptyArchive: true
}
}
}
}
}Option 2: Docker Agent with Chrome
Docker agents give you consistent browser environments across all Jenkins runs:
pipeline {
agent {
docker {
image 'selenium/standalone-chrome:latest'
args '--shm-size=2g'
}
}
stages {
stage('Install') {
steps {
sh 'pip install selenium pytest webdriver-manager'
}
}
stage('Test') {
steps {
sh '''
pytest tests/e2e/ \
--junitxml=results.xml \
-v
'''
}
post {
always {
junit 'results.xml'
}
}
}
}
}The selenium/standalone-chrome image from SeleniumHQ includes Chrome, ChromeDriver, and Xvfb pre-configured. --shm-size=2g is important — Chrome uses /dev/shm for memory-mapped files and the Docker default (64MB) causes crashes.
Option 3: Xvfb for Non-Headless Testing
Some tests require a visible browser (Flash content, certain UI components). Use Xvfb to create a virtual display:
pipeline {
agent any
stages {
stage('Install Xvfb') {
steps {
sh 'sudo apt-get install -y xvfb'
}
}
stage('Test with Display') {
steps {
sh '''
export DISPLAY=:99
Xvfb :99 -screen 0 1920x1080x24 &
XVFB_PID=$!
pytest tests/e2e/ --junitxml=results.xml
kill $XVFB_PID
'''
}
post {
always {
junit 'results.xml'
}
}
}
}
}The Jenkins Xvfb plugin handles this more cleanly — install it via Manage Jenkins → Plugins, then configure in job settings. The plugin starts Xvfb before your pipeline and stops it after, without manual process management.
Capturing Screenshots on Failure
Screenshots are essential for debugging Selenium failures in CI. Add a pytest fixture that captures them:
# conftest.py
import pytest
import os
from datetime import datetime
@pytest.fixture(autouse=True)
def screenshot_on_failure(request, driver):
yield
if request.node.rep_call.failed:
screenshot_dir = 'screenshots'
os.makedirs(screenshot_dir, exist_ok=True)
timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
filename = f"{screenshot_dir}/{request.node.name}_{timestamp}.png"
driver.save_screenshot(filename)
print(f"\nScreenshot saved: {filename}")
@pytest.hookimpl(tryfirst=True, hookwrapper=True)
def pytest_runtest_makereport(item, call):
outcome = yield
rep = outcome.get_result()
setattr(item, f"rep_{rep.when}", rep)Archive screenshots in your Jenkinsfile:
post {
always {
junit 'selenium-results.xml'
archiveArtifacts(
artifacts: 'screenshots/**/*.png',
allowEmptyArchive: true,
fingerprint: true
)
}
}Screenshots appear in Build → Artifacts and can be viewed in the Jenkins UI.
Parallel Browser Testing in Jenkins
Run tests across multiple browsers simultaneously:
stage('Cross-Browser Tests') {
parallel {
stage('Chrome') {
agent {
docker {
image 'selenium/standalone-chrome:latest'
args '--shm-size=2g'
}
}
steps {
sh 'pip install -r requirements.txt'
sh 'pytest tests/e2e/ --browser=chrome --junitxml=results-chrome.xml'
}
post {
always {
junit 'results-chrome.xml'
archiveArtifacts 'screenshots/**'
}
}
}
stage('Firefox') {
agent {
docker {
image 'selenium/standalone-firefox:latest'
args '--shm-size=2g'
}
}
steps {
sh 'pip install -r requirements.txt'
sh 'pytest tests/e2e/ --browser=firefox --junitxml=results-firefox.xml'
}
post {
always {
junit 'results-firefox.xml'
}
}
}
}
}Each parallel stage gets its own Docker container with the appropriate browser. Results merge in the Jenkins test report.
Common Jenkins Selenium Failures
"Chrome failed to start: exited abnormally": Missing --no-sandbox flag, or /dev/shm too small. Add both flags and --shm-size=2g if using Docker.
"ChromeDriver executable not found": Use webdriver-manager to install automatically, or ensure ChromeDriver version matches Chrome version on the agent.
"Element not interactable": JavaScript hasn't finished rendering. Replace time.sleep() with WebDriverWait:
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
element = WebDriverWait(driver, 10).until(
EC.element_to_be_clickable((By.ID, "submit-button"))
)
element.click()Tests pass locally but fail in Jenkins: Window size differences cause layout changes. Set --window-size=1920,1080 in Chrome options. Also check that your test URLs point to the right environment.
Port conflicts when running multiple tests: Each test that starts a browser uses ports. If running too many parallel tests on one agent, ports can conflict. Limit parallelism or use Docker containers (isolated networking).
Managing ChromeDriver Versions
ChromeDriver version must match the installed Chrome version. This breaks regularly when Chrome auto-updates on agents. Solutions:
- webdriver-manager (recommended): Automatically downloads matching ChromeDriver
- Pin Chrome version: Use
google-chrome-stable=<version>and disable auto-updates - Docker images: Use SeleniumHQ images where Chrome and ChromeDriver versions are matched
from webdriver_manager.chrome import ChromeDriverManager
from selenium.webdriver.chrome.service import Service
service = Service(ChromeDriverManager().install())
driver = webdriver.Chrome(service=service, options=options)webdriver-manager checks the Chrome version and downloads the matching driver on each run. Slower on cold cache but eliminates version mismatch errors.
When to Consider Alternatives
Managing Selenium infrastructure in Jenkins works, but it's non-trivial maintenance. ChromeDriver version management, Docker image updates, Xvfb configuration, screenshot handling — these are all operational overhead that doesn't directly contribute to test quality.
HelpMeTest takes a different approach: managed cloud execution for Playwright tests (the modern Selenium replacement) where infrastructure is handled externally. Your Jenkins pipeline triggers a HelpMeTest run via API, and results come back without managing any browser setup. At $0.003 per test run with AI-assisted test generation, it's worth evaluating if your team finds itself spending more time on Jenkins Selenium configuration than on actual test writing.
Summary
For Jenkins Selenium integration:
- Use headless Chrome with
--no-sandbox --disable-dev-shm-usageflags - Use
webdriver-managerto handle ChromeDriver versions - Use Docker agents (
selenium/standalone-chrome) for consistent environments - Capture screenshots in
conftest.pyhooks and archive as build artifacts - Use parallel stages for cross-browser testing
- Publish results with
junitinpost { always { } }blocks
Try HelpMeTest for managed browser test execution that integrates with your Jenkins pipeline.