How to Run Jenkins Tests Locally: Unit and Functional Testing Guide

To run Jenkins tests locally, activate Maven profiles (-Plight-test, -Psmoke-test, or -Pall-tests) with mvn test, requiring JDK 21+ and Maven 3.9.6+ installed.

The jenkinsci/jenkins repository uses a Maven-driven build system that splits the test suite into fast unit tests and comprehensive functional tests requiring a running Jenkins instance. Understanding how to execute these tests on your workstation is essential for contributing core code or debugging failures before submitting a pull request.

Prerequisites for Running Jenkins Tests

Before executing the test suite, ensure your environment meets the requirements documented in CONTRIBUTING.md (lines 12-15). You need JDK 21 or newer (Temurin or OpenJDK) and Maven 3.9.6+ installed. The build configuration in the parent pom.xml and test/pom.xml relies on specific JVM arguments (e.g., --add-opens directives) that require modern JDK features.

Understanding the Three Test Profiles

Jenkins organizes tests into three Maven profiles defined in the project POMs. These profiles determine whether you run fast unit tests or the full functional suite:

• light-test – Executes only unit tests from the jenkins-test module. This profile provides rapid feedback during core development.
• smoke-test – Runs unit tests plus a curated set of functional tests marked with the SmokeTest group. This offers a balance between speed and integration coverage.
• all-tests – Executes the complete suite of unit and functional tests. This is the default profile and may take over 30 minutes on a typical workstation.

The functional test harness, configured in test/pom.xml (lines 31-33), starts an embedded Jetty-based Jenkins instance using the jenkins-war artifact with type executable-war.

Building the Project Without Tests

First, compile the source and install artifacts into your local Maven repository without running tests to save time:

git clone https://github.com/jenkinsci/jenkins.git
cd jenkins
mvn clean install -DskipTests

Executing Specific Test Suites

Run Only Unit Tests (Light Profile)

For quick validation of core logic, use the light-test profile:

mvn -Plight-test test

This executes only the JVM-based unit tests, skipping the heavier functional tests that require a running Jenkins instance.

Run Smoke Tests for Integration Checks

To verify integration points without waiting for the full suite, run the smoke tests:

mvn -Psmoke-test test

This profile selects functional tests annotated with the SmokeTest group, providing faster coverage of critical paths.

Run the Complete Test Suite

To perform full verification before merging, execute all tests:

mvn -Pall-tests test

Because this is the default profile, you can also run mvn test, but explicitly declaring -Pall-tests ensures clarity in CI scripts.

Running Individual Tests

Maven Surefire allows you to run a specific test class or method using the -Dtest selector. This works with any profile:

# Run a specific test class

mvn -Plight-test test -Dtest=HudsonSecurityTest

# Run a specific test method

mvn -Plight-test test -Dtest=HudsonSecurityTest#testCsrfProtection

Debugging Functional Tests

To debug functional tests, attach a remote debugger to the Maven process by setting MAVEN_OPTS with JDWP flags before running the command:

MAVEN_OPTS='-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005' \
mvn -Pall-tests test

IntelliJ IDEA users: You must disable the auto-injection of jenkins.addOpens under Settings → Build, Execution, Deployment → Maven → Running Tests to prevent startup failures, as specified in CONTRIBUTING.md (lines 15-18).

Generating Code Coverage Reports

Enable the enable-jacoco profile to generate JaCoCo coverage reports for the unit test portion:

mvn -Plight-test,enable-jacoco test

This profile configures the Surefire plugin to output coverage data for analysis.

Frontend Assets for UI Tests

Functional tests involving UI components rely on frontend assets. If you are working on UI code, start the Yarn development server in a separate terminal after building the WAR:

export PATH=$PWD/node:$PWD/node/node_modules/corepack/shims:$PATH
yarn start

The default functional test run uses pre-built assets, so the Yarn step is only necessary when developing or debugging UI changes.

Summary

• Three Maven profiles control test scope: light-test (unit only), smoke-test (unit + curated functional), and all-tests (full suite).
• JDK 21+ and Maven 3.9.6+ are required according to CONTRIBUTING.md.
• Use -Dtest=ClassName#methodName to run specific tests via Surefire.
• Attach a debugger by setting MAVEN_OPTS with JDWP flags before running mvn test.
• IntelliJ users must disable jenkins.addOpens auto-injection to avoid startup failures.
• Enable the enable-jacoco profile to generate coverage reports for unit tests.

Frequently Asked Questions

What is the difference between light-test and smoke-test profiles?

The light-test profile executes only the unit tests in the jenkins-test module, providing rapid feedback for core logic changes. The smoke-test profile runs those same unit tests plus a curated subset of functional tests marked with the SmokeTest group, verifying integration points without the overhead of the full suite.

How do I debug a failing Jenkins test in IntelliJ IDEA?

Set the MAVEN_OPTS environment variable with JDWP flags (e.g., -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005) before running mvn test. Additionally, you must disable the auto-injection of jenkins.addOpens in IntelliJ under Settings → Build, Execution, Deployment → Maven → Running Tests to prevent startup failures, as noted in CONTRIBUTING.md.

Can I run a single test method instead of the entire class?

Yes. Use Maven Surefire's -Dtest syntax with a hash separator: mvn -Plight-test test -Dtest=ClassName#methodName. This executes only the specified method from the test class rather than the whole class.

Why do I need JDK 21 to run Jenkins tests?

The Jenkins project requires JDK 21 or newer to build and run the test suite, as specified in CONTRIBUTING.md (lines 12-15). The Maven configuration in pom.xml and test/pom.xml passes specific --add-opens JVM arguments that rely on newer JDK module system features used by the Jenkins core and its test harness.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}