What is Surefire?

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

Surefire supports JUnit 4 (4.12+), JUnit 5 (Jupiter), and TestNG (6.14.3+).
Until 3.5.x, each type was executed via a dedicated provider module. From 3.6.0 on, there is only one unified provider.
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>unified provider for all JUnit 3+ versions</i>"]
    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

    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

graph LR
    subgraph "Before — 3.5.x (5 providers)"
        M1["AbstractSurefireMojo"] --> PD1["ProviderDetector<br/>(priority-based)"]
        PD1 --> JP1["surefire-junit-platform"]
        PD1 --> TNG1["surefire-testng"]
        PD1 --> J471["surefire-junit47"]
        PD1 --> J41["surefire-junit4"]
        PD1 --> J31["surefire-junit3"]
    end

graph LR
    subgraph "After — 3.6.0 (1 provider)"
        M2["AbstractSurefireMojo"] --> PD2["Simplified detection"]
        PD2 --> JP2["surefire-junit-platform"]
        JP2 --> VE["Vintage Engine<br/>(JUnit 3/4)"]
        JP2 --> JE["Jupiter Engine<br/>(JUnit 5)"]
        JP2 --> TE["TestNG Engine<br/>(TestNG)"]
    end

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();
}

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

Since 3.6.0, test filtering by groups, categories, or tags is handled via the JUnit Platform's native tag expression syntax.

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).

Stack trace filtering

A new StackTraceProvider optimizes memory usage by truncating stack traces to 15 frames and filtering JDK packages by default. This is configurable:

<configuration>
    <stackTraceFilterPrefixes>
        <prefix>org.springframework.</prefix>
        <prefix>org.junit.</prefix>
    </stackTraceFilterPrefixes>
</configuration>

When not specified or empty, the default filters (java., javax., sun., jdk.) apply.

Stack Trace Memory Optimization

<!-- Custom prefixes (replaces defaults) -->
<configuration>
    <stackTraceFilterPrefixes>
        <prefix>org.springframework.</prefix>
        <prefix>org.junit.</prefix>
    </stackTraceFilterPrefixes>
</configuration>

# Command line
mvn test -Dsurefire.stackTraceFilterPrefixes=org.springframework.,org.junit.