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

> Learn to run Jenkins tests locally with Maven profiles like -Plight-test or -Pall-tests. Follow our guide for unit and functional testing on your machine. Requires JDK 21+ and Maven 3.9.6+.

- Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins)
- Tags: testing
- Published: 2026-08-01

---

**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`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) and [`test/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash

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

```bash
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`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md) (lines 15-18).

## Generating Code Coverage Reports

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

```bash
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:

```bash
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`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/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`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md) (lines 12-15). The Maven configuration in [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) and [`test/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/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.