Jenkins Selenium Integration: Running Browser Tests in CI

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:

  1. Headless Chrome — simplest, no display required, Chrome 60+
  2. Xvfb (X Virtual Framebuffer) — virtual display for non-headless scenarios
  3. 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-stable

Or 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:

  1. webdriver-manager (recommended): Automatically downloads matching ChromeDriver
  2. Pin Chrome version: Use google-chrome-stable=<version> and disable auto-updates
  3. 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:

  1. Use headless Chrome with --no-sandbox --disable-dev-shm-usage flags
  2. Use webdriver-manager to handle ChromeDriver versions
  3. Use Docker agents (selenium/standalone-chrome) for consistent environments
  4. Capture screenshots in conftest.py hooks and archive as build artifacts
  5. Use parallel stages for cross-browser testing
  6. Publish results with junit in post { always { } } blocks

Try HelpMeTest for managed browser test execution that integrates with your Jenkins pipeline.

Read more

Start now free