Integrate Selenium WebDriver with Jenkins by running your project’s existing test command in a Jenkins Pipeline on an agent that has the required runtime and browser environment. For Java projects, declare Selenium in the build tool—commonly Maven—and let Jenkins orchestrate the build. Start with a browser installed on the agent; use Selenium Grid when you need remote browsers, parallel sessions, or broader browser and operating-system coverage.
Before you add Selenium tests to Jenkins
Jenkins does not need a Selenium-specific job type. Your project owns the Selenium dependency, test framework, and test command; the Pipeline checks out the code, runs that command, and publishes the resulting reports.
- Confirm the tests pass using the same command developers run locally.
- Identify the project runtime, Selenium binding, test framework, browser, and driver requirements.
- Record required environment variables, credentials, and any application or test-data setup.
- Identify where the test framework writes machine-readable reports and failure artifacts.
Declare Selenium in the project
For Java, Selenium’s installation guide demonstrates adding org.seleniumhq.selenium:selenium-java as a Maven dependency. Select a current release compatible with your project’s Java baseline; there is no single version number that fits every project. See the Selenium library installation guide and check current Selenium downloads before pinning a version.
Run the test command in a Jenkins Pipeline
This declarative Pipeline illustrates a Maven project whose tests run with mvn -B test and write JUnit XML files under target/surefire-reports/. Adjust the command and report path to match your repository; the sample paths are not universal.
pipeline {
agent any
stages {
stage('Checkout') {
steps { checkout scm }
}
stage('WebDriver tests') {
steps {
sh 'mvn -B test'
}
}
}
post {
always {
junit 'target/surefire-reports/*.xml'
}
}
}Use sh for a Unix-like agent; on Windows, use the appropriate batch step and command. Set an agent label instead of any when only certain agents have the needed browser or runtime. The junit step records test results in Jenkins when matching XML reports exist.
Manage Maven and JDK through Jenkins when useful
The Jenkins Pipeline Maven Integration plugin provides withMaven for Maven configuration. Depending on your Jenkins setup, it can select configured JDK and Maven installations, apply settings, and support Maven report publishing. Use it when managed tools or settings are part of your team’s workflow; a plain Maven command can be enough when the agent already has the correct tools. See the Pipeline Maven Integration documentation.
Choose where the browser runs
| Approach | Best fit | Trade-off |
|---|---|---|
| Browser on a Jenkins agent | A small suite or first CI integration | Simple to operate, but the agent’s browser and driver must remain compatible and launchable. |
| Selenium Grid | Remote browsers, parallel sessions, or browser and platform coverage | Adds a shared remote execution service, network configuration, and security responsibilities. |
| Dockerized test stage | Packaging test dependencies for more repeatable execution | Requires Docker-capable Jenkins execution and maintained images; browser and Grid networking still need attention. |
Start with a local browser
For the simplest design, install a supported browser on the Jenkins agent and ensure the agent user can launch it. The current Selenium Grid getting-started guide lists installed browsers and drivers as prerequisites and notes that Selenium Manager can configure drivers automatically when enabled. Verify browser, driver, Selenium, and Java compatibility for the versions you select rather than relying on assumptions from an older tutorial. The guide currently lists Java 11 or higher as a getting-started prerequisite; check the requirements for your selected releases.
Move to Grid for remote or parallel sessions
Selenium Grid routes WebDriver commands to remote browser instances and supports parallel execution and browser or platform coverage. Configure the test code to create a RemoteWebDriver pointed at the Grid URL; the Selenium getting-started guide uses port 4444 as the default endpoint and describes standalone and Hub/Node deployment roles. See the Selenium Grid overview and Grid getting-started guide.
A Grid endpoint is sensitive infrastructure, not a public testing URL. Selenium warns that an exposed Grid can let outsiders reach infrastructure, internal applications, and files, or run binaries. Keep it on a private network or restrict access with appropriate firewall and access controls.
Use Docker when its boundaries are clear
Jenkins Pipeline can execute stages in Docker images when the Docker Pipeline plugin is installed and the agent is configured to run Docker. A stage-specific image or repository Dockerfile can package runtime dependencies. You still need to plan browser versions, fonts, shared memory, and networking to an application or Grid. Consult Jenkins’ Docker with Pipeline guide for plugin and agent requirements.
Rank #4
Publish useful results and failure artifacts
Publish the test framework’s machine-readable results with Jenkins’ JUnit support, and preserve screenshots or logs when a test fails. Keep test assertions distinct from environment failures so a missing browser, unreachable Grid, exhausted session capacity, or incompatible versions do not look like an application regression. Report formats, output paths, and useful artifacts depend on the test framework and project.
Selenium’s Grid guide suggests 1 CPU and 1 GB RAM per browser as a reference allocation, while cautioning that actual resource needs vary and should be measured. Treat this as a starting point for capacity planning, not a guarantee or benchmark.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Best Value
Troubleshoot common Jenkins and WebDriver failures
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Browser does not start on the agent | Browser missing, agent user lacks permissions, or required runtime dependencies are absent. | Run the test as the Jenkins agent user; confirm the browser is installed and launchable in that environment. |
| Driver or browser version error | Selected browser, driver, Selenium, or Java versions are incompatible. | Check compatibility for the exact versions in use. If Selenium Manager is enabled, confirm the agent can use it and reach the resources it needs. |
| Could not connect to Grid | Wrong RemoteWebDriver URL, Grid not running, or agent-to-Grid network access blocked. | Verify the configured endpoint and port, Grid health, and network path from the Jenkins agent. |
| Grid sessions fail under load | Insufficient browser slots or host resources for concurrent sessions. | Check Grid capacity and host utilization; reduce test concurrency or add capacity based on measured demand. |
| Build passes but Jenkins shows no test results | The JUnit glob does not match the report location, or the test command did not generate reports. | Inspect the workspace after the test stage and set the junit path to the actual report files. |
| Docker stage cannot reach the application or Grid | Container network configuration does not provide the required route or hostname. | Check the container’s network and service names, then verify reachability from inside the stage environment. |
| Tests behave differently on CI | Agent configuration, environment variables, browser settings, or test data differ from local execution. | Compare the runtime and browser environment and provide explicit configuration and stable test data. |
Do not make the legacy Jenkins Selenium plugin the default
The current Jenkins Selenium plugin page describes a legacy Selenium 3 Grid plugin, reports an unresolved warning about absent CSRF protection and potential OS command injection, and says the plugin is up for adoption. Prefer ordinary Pipeline steps and a maintained project or Grid setup unless you are reviewing an existing deployment and have assessed its risks.
Or skip the browser setup
If the task is to capture a web page rather than run interactive browser tests, ScreenshotNeo offers a screenshot API and MCP server. One GET request returns an image or PDF; it is not a replacement for Selenium assertions or browser interaction tests. The API removes supported cookie and consent banners, newsletter popups, and chat widgets before capture, with each step configurable. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf. Plans include 1,000 shots per month free with no card; paid plans start at $5 for 3,000 shots. See ScreenshotNeo.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for parameters and setup, then sign up for 1,000 free screenshots a month with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
