What is Surefire?

Apache Maven Surefire is the test execution framework for Maven. It ships three plugins:

Surefire supports JUnit 3, JUnit 4, JUnit 5 (Jupiter), TestNG, and plain POJO tests — each via a dedicated provider module. Tests execute in a forked JVM that communicates results back to Maven through a binary event stream protocol.

Module Map

The project is a multi-module Maven reactor with 14+ modules organized in layers.

graph TD
    subgraph "Layer 5 — Maven Plugins"
        MSP["maven-surefire-plugin"]
        MFP["maven-failsafe-plugin"]
        MRP["maven-surefire-report-plugin"]
    end

    subgraph "Layer 4 — Shared Plugin Logic"
        MSC["maven-surefire-common<br/><i>AbstractSurefireMojo, ForkStarter, BooterSerializer</i>"]
    end

    subgraph "Layer 3 — Forked JVM Bootstrap"
        SB["surefire-booter<br/><i>ForkedBooter, PpidChecker, IsolatedClassLoader</i>"]
    end

    subgraph "Layer 2 — Extension Points"
        SEA["surefire-extensions-api<br/><i>ForkNodeFactory, reporters — plugin side</i>"]
        SES["surefire-extensions-spi<br/><i>MasterProcessChannelProcessorFactory — fork side</i>"]
    end

    subgraph "Layer 1 — Core API"
        SA["surefire-api<br/><i>SurefireProvider SPI, events, stream codec</i>"]
    end

    subgraph "Layer 0 — Foundations"
        SLA["surefire-logger-api"]
        SSU["surefire-shared-utils<br/><i>Shaded: commons-lang3, commons-io, etc.</i>"]
    end

    subgraph "Providers — Loaded in Forked JVM"
        JP["surefire-junit-platform<br/><i>JUnit 5 / Jupiter</i>"]
        J4["surefire-junit4"]
        J47["surefire-junit47<br/><i>Parallel + categories</i>"]
        J3["surefire-junit3<br/><i>JUnit 3 + POJO</i>"]
        TNG["surefire-testng"]
    end

    subgraph "Shading"
        SF["surefire-shadefire<br/><i>Self-test: shades provider for Surefire's own build</i>"]
    end

    subgraph "Reporting"
        SRP["surefire-report-parser"]
    end

    subgraph "Filtering"
        SG["surefire-grouper<br/><i>JavaCC category expression parser</i>"]
    end

    MSP --> MSC
    MFP --> MSC
    MSC --> SA
    MSC --> SB
    MSC --> SEA
    SB --> SA
    SB --> SES
    SEA --> SA
    SES --> SA
    SA --> SLA
    SA --> SSU
    SB --> SSU
    MRP --> SRP
    SRP --> SLA

Forked JVM Architecture

The most important architectural concept: tests never run in the Maven JVM. They execute in a separate forked process.

sequenceDiagram
    participant User as mvn test
    participant Mojo as AbstractSurefireMojo<br/>(Maven JVM)
    participant FS as ForkStarter
    participant BS as BooterSerializer
    participant Fork as ForkedBooter.main()<br/>(Forked JVM)
    participant Prov as SurefireProvider
    participant FC as ForkClient

    User->>Mojo: execute()
    Mojo->>Mojo: Auto-detect provider<br/>(ProviderDetector)
    Mojo->>Mojo: Resolve provider classpath<br/>(SurefireDependencyResolver)
    Mojo->>FS: fork()

    FS->>BS: Serialize config to .properties file
    FS->>FS: Build JVM command line<br/>(ForkConfiguration)
    FS->>Fork: Launch process<br/>(java -cp ... ForkedBooter)

    Fork->>Fork: setupBooter()<br/>- Read .properties file<br/>- Set system properties<br/>- Connect communication channel<br/>- Start PpidChecker (orphan detection)

    Fork->>Prov: Load provider via IsolatedClassLoader
    Fork->>Prov: invoke(testSet)
    Prov->>Prov: Run tests (JUnit/TestNG/etc.)

    loop For each test event
        Prov->>Fork: Report event via RunListener
        Fork-->>FC: Binary event stream<br/>(EventChannelEncoder → pipe/TCP)
        FC-->>Mojo: Decoded Event objects<br/>(EventDecoder → ForkedProcessEventNotifier)
        Mojo->>Mojo: Update console + write XML reports
    end

    Fork-->>FC: ControlByeEvent
    FC-->>FS: Run complete
    FS-->>Mojo: RunResult (pass/fail/skip counts)

Provider Model

public interface SurefireProvider {
    // Returns test classes/suites — determines fork granularity
    Iterable<Class<?>> getSuites();

    // Executes tests; forkTestSet is null for "run all" or a Class for per-test forking
    RunResult invoke(Object forkTestSet) throws TestSetFailedException, ReporterException;

    // Graceful cancellation on timeout
    void cancel();
}

flowchart TD
    Start["Scan test classpath"] --> SPI{"SPI configured?<br/>(META-INF/services)"}
    SPI -->|Yes| UseSPI["Use SPI provider(s)"]
    SPI -->|No| JP{"JUnit Platform<br/>on classpath?"}
    JP -->|Yes| UseJP["Use surefire-junit-platform"]
    JP -->|No| TNG{"TestNG<br/>on classpath?"}
    TNG -->|Yes| UseTNG["Use surefire-testng"]
    TNG -->|No| J47{"JUnit ≥4.7 AND<br/>(parallel OR groups)?"}
    J47 -->|Yes| UseJ47["Use surefire-junit47"]
    J47 -->|No| J4{"JUnit 4.x<br/>on classpath?"}
    J4 -->|Yes| UseJ4["Use surefire-junit4"]
    J4 -->|No| J3["Use surefire-junit3<br/>(always applicable — fallback)"]

Communication Protocol

The forked JVM communicates with Maven through a binary event stream. Events flow one-way: fork → Maven. Commands flow the other way: Maven → fork.

ClassLoader Isolation

The forked JVM uses a layered classloader strategy to prevent classpath conflicts:

graph TD
    Boot["Bootstrap ClassLoader<br/>(JDK classes)"]
    System["System ClassLoader<br/>(ForkedBooter + surefire-booter + surefire-api)"]
    Isolated["IsolatedClassLoader<br/>(Provider + test classes + test dependencies)<br/><b>Child-first delegation</b>"]

    Boot --> System
    System --> Isolated

IsolatedClassLoader extends URLClassLoader with child-first class loading: it calls findClass() before delegating to the parent, ensuring test classes and provider classes take precedence over surefire internals.

Three classpaths are maintained:

For Java 9+, ModularClasspathConfiguration adds --module-path and --add-reads / --add-opens directives.

Shading Strategy

Two modules handle classpath isolation at build time:

Process Monitoring

The forked JVM must detect when the parent Maven process dies to avoid becoming an orphan. Two complementary mechanisms exist, configured via ProcessCheckerType:

Extensions SPI

Surefire provides two extension points that allow customizing fork communication and reporting:

Reporting

Test results flow through a layered reporting pipeline:

1. Provider generates ReportEntry events (test started, succeeded, failed, etc.)
2. TestSetRunListener receives events and delegates to registered reporters
3. StatelessXmlReporter writes TEST-*.xml files (JUnit/Ant-compatible format)
4. ConsoleOutputFileReporter writes *-output.txt files with captured stdout/stderr
5. DefaultReporterFactory manages reporter lifecycle and aggregates RunResult across forks

When multiple forks run in parallel, each fork has its own DefaultReporterFactory. Results are merged by ReportsMerger into a single aggregate RunResult that determines the build status.

The maven-surefire-report-plugin reads the XML files (via surefire-report-parser) and generates HTML reports — it operates post-build and is independent of the execution pipeline.

Group / Category Filtering

The surefire-grouper module provides test filtering by JUnit 4 categories or TestNG groups.

Build and Test

# Full build with unit tests
mvn clean install

# Full build with integration tests
mvn clean install -P run-its

# Build a single module
mvn clean install -pl surefire-booter

# Run a single test
mvn test -pl surefire-booter -Dtest=ForkedBooterTest

# Run a single integration test
mvn verify -pl surefire-its -Prun-its -Dit.test=JUnit47RedirectOutputIT

# IDE setup (required before importing)
mvn install -P ide-development -f surefire-shared-utils/pom.xml
mvn compile -f surefire-grouper/pom.xml

Requirements: Maven 3.6.3+, JDK 8+ (source level 8, animal-sniffer enforces Java 8 API).