Jenkins pipeline for Selenium: Step by Step (2026)

TL;DR

A robust Selenium pipeline runs a Maven or Gradle test project on a clean agent, launches browsers locally or through Selenium Grid, and always publishes JUnit XML plus failure evidence. The complete Java and declarative Jenkins examples below cover tool setup, headless execution, credentials, parallelism, Grid, and troubleshooting.

Key Takeaways

• Build Selenium tests with a locked Java and Maven toolchain on disposable Jenkins agents.
• Let Selenium Manager resolve local drivers, or use a pinned Selenium Grid endpoint for centralized browsers.
• Create a fresh WebDriver per test and quit it reliably to support safe parallel execution.
• Publish Surefire JUnit XML from an always-running post block and archive screenshots separately.
• Use explicit waits around observable conditions, not fixed sleeps or global retry loops.
• Treat browser capacity, test data, and Grid session queues as measurable pipeline resources.

A Jenkins pipeline for Selenium turns a browser automation project into a repeatable quality gate. The reliable design uses a known JDK and build tool, creates browsers through supported Selenium APIs, runs isolated tests, publishes JUnit-compatible XML, and preserves screenshots and logs when failures occur.

This tutorial uses Java 21, Maven, JUnit 5, Selenium WebDriver, and a declarative Jenkinsfile. It begins with a local Chrome agent, then adds Selenium Grid, parallel execution, secrets, and production controls. The patterns also translate to TestNG or Gradle, but keeping one complete stack makes every example runnable.

TL;DR

The core Jenkins flow is checkout -> verify toolchain -> mvn clean test -> publish Surefire XML -> archive screenshots. A Grid-based job adds service readiness and capacity management before the test stage.

1. What a Jenkins pipeline for Selenium is responsible for

Selenium code can compile correctly and still fail because the agent has the wrong browser, the driver cannot start, the display is missing, the Grid has no capacity, or shared test data was changed by another build. Jenkins must make these dependencies visible.

A good pipeline controls five boundaries. First, it selects a reproducible Java and Maven runtime. Second, it defines where browser sessions run, locally on the agent or remotely on Grid. Third, it supplies non-secret environment configuration and securely binds credentials. Fourth, it limits concurrency to the capacity of the browser infrastructure and target application. Fifth, it publishes evidence even after the test command returns a nonzero exit code.

Keep the Jenkinsfile with the test code so pipeline changes receive the same review as framework changes. Use agents for execution, not the Jenkins controller. Prefer clean workspaces or disposable agents because leftover drivers, browser profiles, compiled classes, and screenshots can produce misleading behavior.

The test process must own WebDriver lifecycle. Jenkins should not attempt to kill individual driver processes after each case. Every test should create its own driver and call quit() in a reliable teardown. Pipeline cleanup is a final safety net, not a substitute for correct framework lifecycle.

2. Create the Maven and JUnit 5 project

Use this minimal pom.xml as a valid starting point. The versions shown are known compatible baselines, and teams should update them through normal dependency review rather than allowing Jenkins to select versions dynamically:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.qajobfit</groupId>
  <artifactId>selenium-ci</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.seleniumhq.selenium</groupId>
      <artifactId>selenium-java</artifactId>
      <version>4.34.0</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.13.3</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.3</version>
        <configuration>
          <useModulePath>false</useModulePath>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Commit pom.xml and preferably the Maven Wrapper files. A wrapper makes the Maven version part of the repository, so Jenkins runs ./mvnw rather than whichever Maven happens to be on the agent. This also keeps developer workstations and CI aligned.

The Maven vs Gradle for testers guide can help teams choosing a build system. The CI principles are the same: lock the build tool, cache downloads cautiously, and never reuse compiled output as an unexplained test input.

3. Write a CI-safe Selenium test

The following test uses current Selenium 4 and JUnit 5 APIs. Selenium Manager is invoked automatically when a local ChromeDriver is created without a driver executable path:

package com.qajobfit.ui;

import java.net.URI;
import java.time.Duration;

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.support.ui.ExpectedConditions;
import org.openqa.selenium.support.ui.WebDriverWait;

import static org.junit.jupiter.api.Assertions.assertTrue;

class ResourcesPageTest {
    private WebDriver driver;

    @BeforeEach
    void startBrowser() {
        ChromeOptions options = new ChromeOptions();
        if (Boolean.parseBoolean(System.getenv().getOrDefault("HEADLESS", "true"))) {
            options.addArguments("--headless=new");
        }
        options.addArguments("--window-size=1440,1000");

        driver = new ChromeDriver(options);
        driver.manage().timeouts().pageLoadTimeout(Duration.ofSeconds(30));
    }

    @Test
    void resourcesPageShowsMainHeading() {
        String baseUrl = System.getenv().getOrDefault(
            "BASE_URL", "https://qajobfit.com"
        );
        driver.get(URI.create(baseUrl).resolve("/resources").toString());

        WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
        var heading = wait.until(
            ExpectedConditions.visibilityOfElementLocated(By.tagName("h1"))
        );

        assertTrue(heading.isDisplayed());
    }

    @AfterEach
    void stopBrowser() {
        if (driver != null) {
            driver.quit();
        }
    }
}

Do not set webdriver.chrome.driver to a path downloaded manually into the repository. Selenium Manager can discover an installed compatible browser and manage a driver for local runs. In tightly controlled enterprises, a prebuilt agent or remote Grid can pin and audit browser binaries instead.

Headless mode removes the display requirement, but it does not remove CPU, memory, network, or font dependencies. Run local and CI tests at the same viewport and inspect rendering-sensitive assertions.

4. Build the first runnable Jenkinsfile

This declarative pipeline expects a Linux agent labeled java21-chrome with Java 21, Chrome, and the committed Maven Wrapper prerequisites:

pipeline {
  agent { label 'java21-chrome' }

  options {
    timestamps()
    disableConcurrentBuilds(abortPrevious: true)
    timeout(time: 45, unit: 'MINUTES')
    buildDiscarder(logRotator(numToKeepStr: '30'))
  }

  environment {
    HEADLESS = 'true'
    BASE_URL = 'https://staging.example.com'
  }

  stages {
    stage('Checkout') {
      steps {
        checkout scm
      }
    }

    stage('Verify toolchain') {
      steps {
        sh 'java -version'
        sh './mvnw --version'
        sh 'google-chrome --version'
      }
    }

    stage('Run Selenium tests') {
      steps {
        sh './mvnw -B -ntp clean test'
      }
    }
  }

  post {
    always {
      junit testResults: 'target/surefire-reports/*.xml',
        allowEmptyResults: true,
        keepLongStdio: true
      archiveArtifacts artifacts: 'target/screenshots/**,target/logs/**',
        allowEmptyArchive: true,
        fingerprint: false
    }
    cleanup {
      deleteDir()
    }
  }
}

-B enables Maven batch mode and -ntp removes transfer progress noise. Neither changes test semantics. The Surefire plugin creates JUnit XML automatically for JUnit 5 tests, and Jenkins consumes those files after success or failure.

The toolchain stage is intentionally visible. Browser and runtime versions in the console make agent drift much easier to diagnose. Once the agent image is immutable and version-labeled, the commands still provide useful evidence at low cost.

Do not use || true after the Maven command. It converts test failures into successful shell steps and defeats the quality gate.

5. Add reusable WebDriver configuration

A framework grows more safely when browser construction has one controlled path. Support local and remote execution through environment variables without duplicating tests:

package com.qajobfit.ui;

import java.net.MalformedURLException;
import java.net.URI;

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;

final class DriverFactory {
    private DriverFactory() {}

    static WebDriver create() {
        ChromeOptions options = new ChromeOptions();
        if (Boolean.parseBoolean(
                System.getenv().getOrDefault("HEADLESS", "true"))) {
            options.addArguments("--headless=new");
        }
        options.addArguments("--window-size=1440,1000");

        String remoteUrl = System.getenv("SELENIUM_REMOTE_URL");
        if (remoteUrl == null || remoteUrl.isBlank()) {
            return new org.openqa.selenium.chrome.ChromeDriver(options);
        }

        try {
            return new RemoteWebDriver(
                URI.create(remoteUrl).toURL(),
                options
            );
        } catch (MalformedURLException exception) {
            throw new IllegalArgumentException(
                "SELENIUM_REMOTE_URL is invalid",
                exception
            );
        }
    }
}

Then replace direct driver construction in @BeforeEach with driver = DriverFactory.create();. The browser capabilities remain typed through ChromeOptions, and the same suite can move between local agents and Grid.

Avoid generic maps full of capability names copied from old tutorials. Selenium 4 supports W3C capabilities, browser option classes, and vendor-prefixed cloud capabilities. Use the typed options class for standard browser settings and document any provider-specific keys.

Keep the factory focused on session creation. Page objects should model user-facing behavior, not choose Grid URLs or headless flags.

6. Run Selenium Grid with Jenkins

Grid separates the Maven test process from browser nodes. It is useful when several jobs share managed browser capacity or when cross-browser coverage would make every Jenkins agent too heavy.

For a controlled environment, Jenkins can start a pinned standalone Chrome container, wait for Grid readiness, run tests, and remove the service:

stage('Start Selenium Grid') {
  steps {
    sh '''
      docker run -d --rm         --name selenium-grid-${BUILD_NUMBER}         -p 4444:4444         --shm-size=2g         selenium/standalone-chrome:4.34.0-20250707
    '''
    sh '''
      for attempt in $(seq 1 30); do
        if curl --fail --silent http://127.0.0.1:4444/status           | grep -q '"ready": true'; then
          exit 0
        fi
        sleep 2
      done
      exit 1
    '''
  }
}

stage('Run against Grid') {
  environment {
    SELENIUM_REMOTE_URL = 'http://127.0.0.1:4444'
  }
  steps {
    sh './mvnw -B -ntp test'
  }
}

post {
  always {
    sh 'docker logs selenium-grid-${BUILD_NUMBER} > target/grid.log 2>&1 || true'
    sh 'docker rm -f selenium-grid-${BUILD_NUMBER} || true'
  }
}

This snippet assumes the agent can run Docker and that host networking exposes the mapped port. Organizations often use a long-running Grid or Kubernetes deployment instead. In that model, Jenkins should call a stable service URL and monitor queue capacity rather than starting infrastructure per build.

The readiness loop checks Grid status instead of sleeping for a guessed number of seconds. A service can have an open port before it can accept sessions, so readiness must reflect the actual API.

7. Capture screenshots on JUnit 5 failures

Jenkins console output rarely shows the browser state. A JUnit 5 extension can capture a screenshot when a test fails, while teardown still closes the session.

Use an AfterTestExecutionCallback so capture occurs after the test method fails but before the test class runs @AfterEach and quits the driver:

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

import org.junit.jupiter.api.extension.AfterTestExecutionCallback;
import org.junit.jupiter.api.extension.ExtensionContext;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.WebDriver;

final class ScreenshotOnFailure implements AfterTestExecutionCallback {
    private final java.util.function.Supplier<WebDriver> driverSupplier;

    ScreenshotOnFailure(
            java.util.function.Supplier<WebDriver> driverSupplier) {
        this.driverSupplier = driverSupplier;
    }

    @Override
    public void afterTestExecution(ExtensionContext context) {
        if (context.getExecutionException().isEmpty()) {
            return;
        }

        WebDriver driver = driverSupplier.get();
        if (!(driver instanceof TakesScreenshot camera)) {
            return;
        }

        byte[] png = camera.getScreenshotAs(OutputType.BYTES);
        String testName = context.getRequiredTestClass().getSimpleName()
            + "_" + context.getDisplayName();
        String safeName = testName.replaceAll(
            "[^a-zA-Z0-9._-]", "_"
        );
        Path path = Path.of(
            "target", "screenshots", safeName + ".png"
        );

        try {
            Files.createDirectories(path.getParent());
            Files.write(path, png);
        } catch (IOException exception) {
            throw new RuntimeException(
                "Could not write screenshot",
                exception
            );
        }
    }
}

Register it as an instance field in the test class so the supplier reads that test instance's driver:

@org.junit.jupiter.api.extension.RegisterExtension
final ScreenshotOnFailure screenshot =
    new ScreenshotOnFailure(() -> driver);

JUnit invokes AfterTestExecutionCallback before user-defined @AfterEach methods, so the browser is still available. This captures test-method failures. If framework setup can fail after starting a browser, add cleanup and evidence handling for that setup path too.

Keep screenshot names unique when tests run in parallel. Include a class, method, invocation ID, or UUID. Archive the directory in post { always { ... } }, and apply access controls if the page contains personal data.

8. Configure waits for stable CI behavior

Fixed sleeps are especially harmful in Jenkins. A fast response still waits the full duration, while a slow response fails after an arbitrary delay. Use explicit waits for observable application conditions. The condition should describe the user-visible outcome, not an implementation delay.

Modern Selenium Java uses Duration with WebDriverWait:

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(12));

wait.until(ExpectedConditions.urlContains("/dashboard"));

var saveButton = wait.until(
    ExpectedConditions.elementToBeClickable(
        By.cssSelector("[data-testid='save-profile']")
    )
);
saveButton.click();

By successMessage = By.cssSelector("[data-testid='save-success']");
wait.until(
    ExpectedConditions.visibilityOfElementLocated(successMessage)
);

Wait for the state that proves the workflow advanced, such as a URL, enabled control, visible confirmation, or completed API-driven UI update. The chosen locator should represent a stable contract with the application, not incidental styling.

Do not mix a large implicit wait with explicit waits. Their timing can become hard to predict. Prefer explicit waits and narrow timeouts based on expected service behavior. For click interception problems, the Selenium ElementClickInterceptedException fixes cover overlays, scrolling, and animation diagnosis.

9. Bind credentials and select environments

Store UI accounts, API setup tokens, and cloud Grid keys in Jenkins credentials. Bind them only around stages that need them:

stage('Authenticated regression') {
  steps {
    withCredentials([
      usernamePassword(
        credentialsId: 'selenium-staging-user',
        usernameVariable: 'E2E_USERNAME',
        passwordVariable: 'E2E_PASSWORD'
      ),
      string(
        credentialsId: 'test-data-api-token',
        variable: 'TEST_DATA_TOKEN'
      )
    ]) {
      sh '''
        set +x
        ./mvnw -B -ntp test
      '''
    }
  }
}

Java reads these through System.getenv("E2E_USERNAME"). Validate that required names exist, but never include values in assertion messages or reports. Jenkins masking can reduce accidental exposure in console output, but URLs, screenshots, browser logs, page source, and third-party reports can still leak secrets.

Represent non-secret environments with an allowlisted choice parameter. Map each option to a known URL inside a Groovy switch or repository configuration. Never accept an arbitrary URL and concatenate it into a shell command.

Separate production credentials from staging credentials and restrict production jobs. Browser tests can mutate data, submit forms, and send notifications, so production execution needs explicit authorization and a read-only or synthetic account strategy.

10. Add safe parallel Selenium execution

Parallel execution works only when each test has its own driver, browser session, data, and independent assertions. A shared static WebDriver will create race conditions as threads navigate the same session.

JUnit 5 parallel execution can be enabled through src/test/resources/junit-platform.properties:

junit.jupiter.execution.parallel.enabled=true
junit.jupiter.execution.parallel.mode.default=concurrent
junit.jupiter.execution.parallel.mode.classes.default=concurrent
junit.jupiter.execution.parallel.config.strategy=fixed
junit.jupiter.execution.parallel.config.fixed.parallelism=4

A fixed value is easier to align with Grid capacity than a dynamic strategy. If Jenkins starts two jobs and each requests four sessions, the Grid needs eight available slots or a predictable queue policy. Coordinate job concurrency, test-thread concurrency, and browser-node capacity as one system.

Use unique data generated from test identifiers or APIs. Do not resolve collisions by adding sleeps. Track queue time separately from test execution time, because a slow build may be waiting for a browser rather than executing slowly.

11. Add cross-browser and suite stages

A pull request can run a fast Chrome smoke suite, while a scheduled build runs Chrome, Firefox, and Edge or another approved browser. Pass the requested browser as an allowlisted environment value and have DriverFactory choose a typed options class.

For a Jenkins matrix:

stage('Cross-browser') {
  matrix {
    axes {
      axis {
        name 'BROWSER'
        values 'chrome', 'firefox'
      }
    }
    stages {
      stage('Test browser') {
        steps {
          sh './mvnw -B -ntp test'
        }
      }
    }
  }
}

The factory should handle only known values and throw an error for anything else. On Grid, browser options determine which node receives the session. Make sure the Grid actually advertises the requested browser versions and platform.

Use JUnit tags for suite selection. Surefire can include tags through the groups configuration or a command-line property selected by your build design. Keep smoke tests meaningful: authentication, one core workflow, and a health-critical read path are more valuable than many shallow page-open checks.

If your organization is comparing browser frameworks rather than adding Grid capacity, Selenium vs Cypress gives a decision framework based on architecture and team needs.

12. Harden the Jenkins pipeline for Selenium

Set timeouts at multiple boundaries. Jenkins needs an overall build timeout. WebDriver needs page-load and script timeouts where appropriate. Explicit waits need condition-specific limits. Grid needs session and queue policies. One enormous timeout at the pipeline level cannot tell engineers which dependency stalled.

Build disposable agent images with fonts, certificates, Chrome, and system libraries already installed. Label or version those images so a browser upgrade is reviewed. If Selenium Manager downloads drivers at runtime, ensure outbound access and caching policy are intentional. Air-gapped environments should use an internal binary supply chain or Grid image.

Limit artifact retention. Screenshots, network logs from proxies, videos from cloud providers, and Grid logs can grow rapidly. Preserve enough builds to debug trends while respecting storage and privacy rules.

Protect Jenkinsfile execution. A pull request that changes shell steps can execute code on the agent, so untrusted forks must not receive production credentials. Use multibranch trust controls and separate agent pools when required.

Finally, test the pipeline itself. Force a failed assertion, an unavailable Grid, an invalid credential, and a browser startup failure. Confirm that each produces a clear red build, useful primary error, published results when available, archived evidence, and successful cleanup.

13. Troubleshoot Selenium failures in Jenkins

If the browser cannot start, compare the installed browser and driver, check agent architecture, inspect Chrome or GeckoDriver output, and verify shared memory and sandbox policy. With Selenium Manager, the console often shows resolution details. With Grid, inspect the Grid status endpoint and node logs.

If Jenkins shows no tests, verify Surefire includes the class naming pattern, JUnit 5 is on the test runtime, and XML exists under target/surefire-reports. allowEmptyResults prevents the publishing step from masking the build's original error, but zero tests should still be investigated.

If elements fail only in CI, capture a screenshot and current URL, then inspect viewport, page state, overlays, feature flags, locale, and authentication. Use an explicit wait around a real condition. Do not immediately add JavaScript clicks, because they bypass user-like interaction and can hide an inaccessible or covered control.

If Grid sessions remain queued, compare requested capabilities with node stereotypes, current slot use, and browser availability. A typo in browserName can look like insufficient capacity. If sessions leak, confirm quit() runs after every test, including setup failures.

If the suite slows over time, separate dependency download, Grid queue, browser startup, application response, and test execution durations. Optimizing the wrong segment usually adds complexity without improving feedback.

Interview Questions and Answers

Q: What stages belong in a Jenkins Selenium pipeline?

A strong baseline has checkout, toolchain verification, dependency resolution and compilation, test execution, result publishing, artifact archiving, and cleanup. Grid-based execution also needs a readiness or capacity check. Publishing must run even when tests fail.

Q: Selenium Manager or a manually downloaded driver?

Selenium Manager is the supported default for local Selenium 4 sessions and reduces driver-path maintenance. For strict enterprise control, I prefer an immutable agent or pinned Grid image containing approved browser components. I do not commit driver binaries into the test repository.

Q: Why is one static WebDriver unsafe for parallel tests?

Threads would issue commands to the same browser session, changing pages and elements underneath one another. Each test or thread needs an independent driver lifecycle. Shared data and accounts must also be isolated.

Q: How do you distinguish a Grid problem from a test problem?

I check whether a session was created, how long it waited in the queue, and whether the node matched requested capabilities. If no session exists, I focus on Grid readiness, capacity, and capabilities. If the session exists, I use test logs, screenshots, browser logs, and application evidence.

Q: How should Jenkins report Selenium results?

Maven Surefire writes JUnit XML, which the Jenkins junit step publishes from an always-running post block. Screenshots and framework logs are separate artifacts. The paths and retention policy should be stable and tested with an intentional failure.

Q: Why avoid Thread.sleep in CI tests?

It waits a fixed time regardless of application state and still fails when the environment takes longer. Explicit waits poll an observable condition until a bounded timeout. They are faster when the condition arrives early and produce more relevant failures.

Q: What security controls apply to Selenium pipelines?

Credentials are bound from Jenkins for the minimum stage and never printed or committed. Reports, screenshots, and logs are protected because they can contain customer or authentication data. Untrusted Jenkinsfile changes cannot access protected secrets or production-capable agents.

Common Mistakes

• Installing an arbitrary browser or driver on a long-lived agent without recording its version.
• Sharing one static WebDriver across parallel JUnit tests.
• Calling close() only, leaving the driver service and other windows alive, instead of quit().
• Publishing Surefire XML only after a successful Maven step.
• Using Thread.sleep as the main synchronization strategy.
• Running more test threads than Grid slots or the target application can support.
• Passing arbitrary user parameters directly into shell commands or capability maps.
• Adding JavaScript click workarounds before investigating overlays and interactability.
• Archiving screenshots and logs without privacy review or retention limits.
• Hiding Maven failures with || true or unconditional successful pipeline results.

Conclusion

A dependable Jenkins pipeline for Selenium makes the browser environment, driver strategy, waits, reports, and cleanup explicit. Start with a clean Java and Maven agent, a fresh WebDriver per test, Surefire XML publishing, and screenshot capture. Add Grid and concurrency only after the local execution path is stable and data is isolated.

Run the sample smoke test through Jenkins, intentionally fail it, and verify the XML, screenshot, console context, and teardown. That failure rehearsal is the fastest proof that the pipeline will help rather than hinder the team during a real regression.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Jenkins pipeline for Playwright: Step by Step (2026)
• CircleCI for test automation: Step by Step (2026)
• Docker for Playwright: Step by Step (2026)
• Docker for Selenium Grid: Step by Step (2026)
• Gatling basics for testers: Step by Step (2026)
• GitHub Actions for Playwright: Step by Step (2026)