This is an automated email from the ASF dual-hosted git repository.
olamy pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-surefire.git
The following commit(s) were added to refs/heads/master by this push:
new 728b66d7e Fix documentation due to code simplification with providers
(#3332)
728b66d7e is described below
commit 728b66d7efb89878f9112dd8208342552161f87e
Author: Olivier Lamy <[email protected]>
AuthorDate: Mon Mar 30 20:25:35 2026 +1000
Fix documentation due to code simplification with providers (#3332)
* Fix documentation due to code simplification with providers
---------
Signed-off-by: Olivier Lamy <[email protected]>
---
.github/copilot-instructions.md | 114 ++++++++------
maven-surefire-plugin/src/site/apt/api.apt.vm | 5 +-
.../src/site/apt/developing.apt.vm | 12 +-
.../fork-options-and-parallel-execution.apt.vm | 4 +-
.../src/site/apt/examples/jpms.apt.vm | 6 +-
.../src/site/apt/examples/junit-platform.apt.vm | 4 +-
.../site/apt/examples/rerun-failing-tests.apt.vm | 15 +-
.../site/apt/examples/skip-after-failure.apt.vm | 24 +--
.../src/site/apt/examples/testng.apt.vm | 2 +-
maven-surefire-plugin/src/site/apt/history.apt.vm | 2 +-
maven-surefire-plugin/src/site/apt/index.apt.vm | 4 +-
maven-surefire-plugin/src/site/apt/usage.apt.vm | 15 +-
maven-surefire-plugin/src/site/fml/faq.fml | 10 +-
.../src/site/markdown/architecture.md | 16 +-
maven-surefire-plugin/src/site/markdown/docker.md | 97 ------------
.../src/site/markdown/whats-new-3-6-0.md | 175 +++++++++++++++++++++
maven-surefire-plugin/src/site/site.xml | 3 +-
surefire-api/src/site/apt/index.apt | 2 -
18 files changed, 283 insertions(+), 227 deletions(-)
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index aa07c8d05..1e4f49429 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,19 +1,21 @@
# Apache Maven Surefire - Copilot Instructions
+This repository contains Apache Maven Surefire - a test framework project
providing the `maven-surefire-plugin`, `maven-failsafe-plugin`, and
`maven-surefire-report-plugin`.
+
## Build Commands
```bash
-# Full build (unit tests only, no integration tests)
+# Full build (unit tests only)
mvn clean install
# Full build with integration tests
-mvn clean install -P run-its
+mvn clean install -Prun-its
# Build a single module
mvn clean install -pl surefire-api
-mvn clean install -pl surefire-booter
+mvn clean install -pl :maven-surefire-report-plugin -am # -am builds
dependencies too
-# Skip tests during build
+# Skip tests
mvn clean install -DskipTests
# Run unit tests for a single module
@@ -25,17 +27,17 @@ mvn test -pl surefire-booter -Dtest=ForkedBooterTest
# Run a single test method
mvn test -pl surefire-booter -Dtest=ForkedBooterTest#testMethod
-# Run a single integration test (requires -P run-its)
+# Run a single integration test (requires -Prun-its)
mvn verify -pl surefire-its -Prun-its -Dit.test=JUnit47RedirectOutputIT
-Dmaven.build.cache.enabled=false
+# Checkstyle
+mvn checkstyle:check
+
# Build site documentation
mvn site -pl maven-surefire-plugin
-
-# Checkstyle (inherited from maven-parent, suppressions in
src/config/checkstyle-suppressions.xml)
-mvn checkstyle:check
```
-## Architecture
+## High-Level Architecture
### Module Dependency Flow
@@ -54,66 +56,82 @@ maven-surefire-common (AbstractSurefireMojo - shared Mojo
logic)
└──▶ surefire-providers/surefire-junit-platform (unified test
execution)
```
-### Forked JVM Architecture
+**Other modules:**
+- `surefire-report-parser` + `maven-surefire-report-plugin` (reporting)
+- `surefire-its` (integration tests)
+- `surefire-shared-utils` (shaded dependencies)
+- `surefire-shadefire` (self-testing support)
-Surefire executes tests in a **forked JVM** separate from the Maven process.
Understanding this split is essential:
-
-- **Maven side** (`maven-surefire-common`): `AbstractSurefireMojo` configures
and launches the fork. `booterclient/` handles communication with the forked
process.
-- **Forked side** (`surefire-booter`): `ForkedBooter.main()` is the entry
point. It deserializes configuration, loads the provider, and runs tests.
Communicates results back via an event-based binary stream protocol.
-- **Shared contract** (`surefire-api`): Defines the `SurefireProvider` SPI,
report events, and the stream protocol used between Maven and forked processes.
-
-### Shading Strategy
+### Forked JVM Architecture
-Two modules exist solely for classpath isolation:
+Tests execute in a **forked JVM** separate from the Maven process:
-- **`surefire-shared-utils`**: Shades commons-lang3, commons-io,
commons-compress, and maven-shared-utils into
`org.apache.maven.surefire.shared.*` to avoid version conflicts with user
projects.
-- **`surefire-shadefire`**: Shades the entire surefire-junit-platform provider
(plus surefire-api, surefire-booter) into `org.apache.maven.shadefire.*` so
Surefire can test **itself** without classpath conflicts during its own build.
+- **Maven side** (`maven-surefire-common`): `AbstractSurefireMojo` configures
and launches the fork. `booterclient/` handles communication.
+- **Forked side** (`surefire-booter`): `ForkedBooter.main()` is the entry
point. Deserializes configuration, loads the provider, runs tests. Results flow
back via binary stream protocol.
+- **Shared contract** (`surefire-api`): Defines the `SurefireProvider` SPI,
report events, and stream protocol.
### Provider Model
-All test frameworks execute through the JUnit Platform provider
(`surefire-providers/surefire-junit-platform`):
+All test frameworks execute through the unified JUnit Platform provider
(`surefire-providers/surefire-junit-platform`):
+- **JUnit 5**: Natively via Jupiter Engine
+- **JUnit 4** (4.12+): Via Vintage Engine
+- **TestNG** (6.14.3+): Via TestNG JUnit Platform Engine
-- **JUnit 5**: Runs natively via Jupiter Engine
-- **JUnit 4** (4.12+): Runs via Vintage Engine
-- **TestNG** (6.14.3+): Runs via TestNG JUnit Platform Engine
+### Shading Strategy
-Legacy providers (`surefire-junit3`, `surefire-junit4`, `surefire-junit47`,
`surefire-testng`) still exist in the tree but are being consolidated.
+- **`surefire-shared-utils`**: Shades commons-lang3, commons-io,
commons-compress, maven-shared-utils into `org.apache.maven.surefire.shared.*`
to avoid classpath conflicts.
+- **`surefire-shadefire`**: Shades the junit-platform provider so Surefire can
test itself without classpath conflicts. The surefire plugin config sets
`useSystemClassLoader=false` for test isolation.
### Integration Tests
-`surefire-its` contains integration tests that launch real Maven builds
against fixture projects in `surefire-its/src/test/resources/`. These require
the `run-its` profile and test the full fork lifecycle end-to-end. They use
`maven-verifier` to invoke Maven and assert on build output.
+`surefire-its` contains integration tests that launch real Maven builds
against fixture projects in `surefire-its/src/test/resources/`. Requires
`-Prun-its`. Uses `maven-verifier` to invoke Maven and assert on build output.
## Key Conventions
### Java Version
-
-Source and target is **Java 8**. The `animal-sniffer-maven-plugin` enforces
the `java18` API signature. JDK 9+ APIs must be accessed via reflection (see
`ProcessHandleChecker` for an example using `ReflectionUtils`).
-
-A `jdk9+` profile auto-activates on JDK 9+ to add `--add-opens` flags for test
execution.
+- Source/target is **Java 8**
+- The `animal-sniffer-maven-plugin` enforces the `java18` API signature
+- JDK 9+ APIs must be accessed via reflection (see `ProcessHandleChecker`
using `ReflectionUtils`)
### Reflection Utilities
-
-When accessing APIs not available at compile time (e.g., Java 9+ APIs), use
`ReflectionUtils` from `surefire-api` rather than raw reflection:
-
+When accessing APIs not available at compile time, use `ReflectionUtils` from
`surefire-api`:
- `tryLoadClass(classLoader, className)` → returns `null` on failure
-- `tryGetMethod(clazz, name, params)` → returns `null` on failure
+- `tryGetMethod(clazz, name, params)` → returns `null` on failure
- `invokeMethodWithArray(target, method, args)` → wraps exceptions in
`SurefireReflectionException`
### IDE Setup
-
-Before importing into an IDE, run:
-
+Before importing into an IDE:
```bash
mvn install -P ide-development -f surefire-shared-utils/pom.xml
-mvn compile -f surefire-grouper/pom.xml
```
-
-The `ide-development` profile resolves IntelliJ IDEA artifact classifier
issues. The `surefire-grouper` module needs a compile pass to generate JavaCC
sources in `target/generated-sources/javacc`.
-
-### Formatting
-
-Follows `.editorconfig`: 4-space indentation for Java, 2-space for XML.
Checkstyle rules are inherited from the Maven parent POM with project-specific
suppressions in `src/config/checkstyle-suppressions.xml`.
-
-### Test Isolation
-
-Surefire uses a **different version of itself** to run its own tests (see
`maven-surefire-plugin` version in `<pluginManagement>` vs
`${project.version}`). The `surefire-shadefire` module enables this
self-testing. The surefire plugin configuration sets
`useSystemClassLoader=false` to isolate the version under test.
+The `ide-development` profile resolves IntelliJ artifact classifier issues.
+
+### Code Formatting
+- **Java**: 4-space indentation
+- **XML**: 2-space indentation
+- Settings defined in `.editorconfig`
+- Checkstyle rules inherited from Maven parent POM with suppressions in
`src/config/checkstyle-suppressions.xml`
+
+### Unit Test Patterns
+
+Report plugin tests (`maven-surefire-report-plugin`) use the
`@MojoTest`/`@InjectMojo` framework:
+- `@MojoTest(realRepositorySession = true)` on the test class
+- `@Basedir("/unit")` sets basedir to `src/test/resources/unit`
+- `@InjectMojo(goal = "report", pom = "test-dir/plugin-config.xml")` injects
the mojo
+- `@Inject MavenProject mavenProject` for project access
+- `getVariableValueFromObject(mojo, "field")` (static import from
`MojoExtension`) to read mojo fields
+- `plugin-config.xml` paths use `${basedir}` which resolves to the `@Basedir`
path
+- Stub `project implementation` classes in plugin-config.xml must be commented
out (they NPE with `@MojoTest`)
+
+## Development Requirements
+
+- **Maven**: 3.6.3+
+- **JDK**: 8+
+- **Memory requirements** for release testing:
+ ```bash
+ # Linux/Unix
+ export MAVEN_OPTS="-server -Xmx512m -XX:MetaspaceSize=128m
-XX:MaxMetaspaceSize=384m -XX:+UseG1GC -XX:+UseStringDeduplication
-XX:+TieredCompilation -XX:TieredStopAtLevel=1 -XX:SoftRefLRUPolicyMSPerMB=50
-Djava.awt.headless=true"
+
+ # Windows
+ set MAVEN_OPTS="-server -Xmx256m -XX:MetaspaceSize=128m
-XX:MaxMetaspaceSize=384m -XX:+UseG1GC -XX:+UseStringDeduplication
-XX:+TieredCompilation -XX:TieredStopAtLevel=1 -XX:SoftRefLRUPolicyMSPerMB=50
-Djava.awt.headless=true"
+ ```
\ No newline at end of file
diff --git a/maven-surefire-plugin/src/site/apt/api.apt.vm
b/maven-surefire-plugin/src/site/apt/api.apt.vm
index eabe558f1..b62f3ecf1 100644
--- a/maven-surefire-plugin/src/site/apt/api.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/api.apt.vm
@@ -54,9 +54,8 @@ Maven Surefire Provider API
[]
- There are four well-known providers within Surefire that are also
implemented this way, so
- examples can be found by looking at the Surefire source code itself.
<<<surefire-junit47>>> is
- the showcase implementation.
+ Since 3.6.0, there is one unified provider within Surefire,
<<<surefire-junit-platform>>>,
+ which is the showcase implementation. Examples can be found by looking at
the Surefire source code itself.
The javadoc on the intefaces mentioned in this article should otherwise be
sufficient to write a provider.
Providers are added as dependencies to the Surefire and Failsafe plugins.
diff --git a/maven-surefire-plugin/src/site/apt/developing.apt.vm
b/maven-surefire-plugin/src/site/apt/developing.apt.vm
index 700ffcd56..d9082c339 100644
--- a/maven-surefire-plugin/src/site/apt/developing.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/developing.apt.vm
@@ -107,7 +107,7 @@ mvn -e -X install | grep Forking
are a "reading list" for getting quickly acquainted with the code:
+---+
-AbstractSurefireMojo#executeAllProviders
+AbstractSurefireMojo#executeAfterPreconditionsChecked
ForkStarter#fork
ForkedBooter#main
+---+
@@ -115,7 +115,7 @@ ForkedBooter#main
* JDK Versions
The surefire booter is capable of booting all the way back to jdk1.8.
Specifically
- this means <<<surefire-api>>>, <<<surefire-booter>>>, <<<common-junit3>>>,
<<<surefire-junit3>>>
+ this means <<<surefire-api>>>, <<<surefire-booter>>>, <<<common-java5>>>,
<<<surefire-junit-platform>>>
and other modules are compiled with source/target 1.8.
* Provider Isolation
@@ -127,11 +127,9 @@ ForkedBooter#main
* Common Provider Modules
- The <<<surefire-providers>>> module contains <<<common-junitXX>>> modules.
These modules
- depend on the <<<XX>>> version of JUnit and can access the JUnit APIs at the
correct
- JUnit version level. Unit tests can also be written that will run with the
- correct JUnit version. At build time, all of the relevant parts of these
"common"
- modules are just shaded into the provider jar files.
+ The <<<surefire-providers>>> module contains the <<<common-java5>>> module
and the
+ unified <<<surefire-junit-platform>>> provider. Since 3.6.0, all test
frameworks
+ (JUnit 4.12+, JUnit 5/6, TestNG 6.14.3+) are executed via the JUnit Platform
provider.
* Shadefire
diff --git
a/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
b/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
index 1cbff1a0d..89160c464 100644
---
a/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
+++
b/maven-surefire-plugin/src/site/apt/examples/fork-options-and-parallel-execution.apt.vm
@@ -148,8 +148,8 @@ Fork Options and Parallel Test Execution
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
- <!-- 4.7 or higher -->
- <version>4.7</version>
+ <!-- 4.12 or higher -->
+ <version>4.13.2</version>
<scope>test</scope>
</dependency>
<dependency>
diff --git a/maven-surefire-plugin/src/site/apt/examples/jpms.apt.vm
b/maven-surefire-plugin/src/site/apt/examples/jpms.apt.vm
index f3727a3a6..bcbe51a6d 100644
--- a/maven-surefire-plugin/src/site/apt/examples/jpms.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/jpms.apt.vm
@@ -35,8 +35,8 @@ Using Java Modularity (JPMS) in Tests
demonstrating the Java Modularity (JPMS).
The JDK version must be 9 or higher. The POM contains the dependency
<<<org.testng:testng:7.1.0>>> which is
- an automatic module. It activates the internal provider
<<<surefire-testng>>> in the plugin. The frameworks with
- assertions API are used, i.e. <<<org.hamcrest:hamcrest:2.2>>> (automatic
module)
+ an automatic module. Since 3.6.0, TestNG tests run via the JUnit Platform
using the TestNG engine.
+ The frameworks with assertions API are used, i.e.
<<<org.hamcrest:hamcrest:2.2>>> (automatic module)
and <<<org.assertj:assertj-core:3.16.1>>> (named module).
+---+
@@ -96,7 +96,7 @@ module test
demonstrating the Java Modularity (JPMS).
The JDK version must be 9 or higher. The POM contains the dependency
<<<junit:junit:4.13>>> which is
- an automatic module. It activates the internal provider
<<<surefire-junit4>>> or <<<surefire-junit47>>> in the plugin.
+ an automatic module. Since 3.6.0, JUnit 4 tests run via the JUnit Platform
using the Vintage Engine.
+---+
<properties>
diff --git a/maven-surefire-plugin/src/site/apt/examples/junit-platform.apt.vm
b/maven-surefire-plugin/src/site/apt/examples/junit-platform.apt.vm
index f3201f996..e70aae86e 100644
--- a/maven-surefire-plugin/src/site/apt/examples/junit-platform.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/junit-platform.apt.vm
@@ -166,8 +166,8 @@ Using JUnit 5 Platform
*** JUnit4 API in test dependencies
This is similar example with JUnit4 in test dependencies of your project POM.
- The Vintage engine artifact has to be in the plugin dependencies; otherwise
the plugin would use
- <<<surefire-junit4>>> provider instead of the <<<surefire-junit-platform>>>
provider.
+ Since 3.6.0, the JUnit Platform provider is always used. Add the Vintage
Engine as a plugin
+ dependency to ensure JUnit 4 tests are executed.
+---+
<dependencies>
diff --git
a/maven-surefire-plugin/src/site/apt/examples/rerun-failing-tests.apt.vm
b/maven-surefire-plugin/src/site/apt/examples/rerun-failing-tests.apt.vm
index 8214f8431..cab385e8f 100644
--- a/maven-surefire-plugin/src/site/apt/examples/rerun-failing-tests.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/rerun-failing-tests.apt.vm
@@ -32,7 +32,7 @@ Rerun Failing Tests
To use this feature through Maven surefire, set the
<<<rerunFailingTestsCount>>> property to be a value larger than 0.
Tests will be run until they pass or the number of reruns has been exhausted.
- << NOTE : This feature is supported for JUnit 4.x, and (since 3.0.0-M4)
JUnit 5.x. >>
+ << NOTE : This feature is supported for JUnit 4.x (4.12+), JUnit 5.x, and
TestNG. >>
+---+
@@ -137,21 +137,20 @@ mvn
-D${thisPlugin.toLowerCase()}.rerunFailingTestsCount=2 test
In the xml report, the running time of a failing test with re-runs will be
the running time of the
<<first failing run>>.
-* Re-run execution in JUnit Providers
+* Re-run execution details
- The provider <<<surefire-junit4>>> executes individual test class and
consequently re-runs failed tests.
- The provider <<<surefire-junit47>>> executes all test classes and re-runs
failed tests afterwards.
+ Since 3.6.0, all test frameworks run via the unified JUnit Platform
provider. Failed tests are
+ re-run after the initial test execution completes.
* Re-run execution in Cucumber JVM
- Since of 2.21.0 the provider <<<surefire-junit47>>> can rerun scenarios
created by <<cucumber-jvm>>
- 2.0.0 and higher.
+ Cucumber-jvm 2.0.0 and higher supports rerunning scenarios via the JUnit
Platform.
* Re-run and skip execution
Since of 2.19.1 you can use parameters <<<skipAfterFailureCount>>> and
<<<rerunFailingTestsCount>>> together.
- This is enabled by providers <<<surefire-junit4>>> and
<<<surefire-junit47>>>. You can run again failed tests
- and skip the rest of the test-set if errors or failures reached
<<<skipAfterFailureCount>>>.
+ You can run again failed tests and skip the rest of the test-set if errors
or failures
+ reached <<<skipAfterFailureCount>>>.
Notice that failed tests within re-run phase are not included in
<<<skipAfterFailureCount>>>.
diff --git
a/maven-surefire-plugin/src/site/apt/examples/skip-after-failure.apt.vm
b/maven-surefire-plugin/src/site/apt/examples/skip-after-failure.apt.vm
index 88576d717..ac6c1582c 100644
--- a/maven-surefire-plugin/src/site/apt/examples/skip-after-failure.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/skip-after-failure.apt.vm
@@ -40,25 +40,9 @@ Skipping Tests After the Nth Failure or Error
Prerequisite
-
- Use ${project.artifactId} 2.19 or higher, JUnit 4.0 or higher, TestNG 5.10 or
- higher, or JUnit Platform 6.0 or higher.
-
- If version of TestNG is lower than 5.10 while the parameter
- <<<skipAfterFailureCount>>> is set, the plugin fails with error:
-
- <<<[ERROR] Failed to execute goal ...: Parameter "skipAfterFailureCount"
- expects TestNG Version 5.10 or higher. java.lang.NoClassDefFoundError:
- org/testng/IInvokedMethodListener>>>
-
-
- If version of JUnit is lower than 4.0 while the parameter
- <<<skipAfterFailureCount>>> is set, the plugin fails with error:
-
- <<<[ERROR] Failed to execute goal ...: Parameter "skipAfterFailureCount"
- expects JUnit Version 4.0 or higher. java.lang.NoSuchMethodError:
- org.junit.runner.notification.RunNotifier.pleaseStop()V>>>
+ Use ${project.artifactId} 2.19 or higher, JUnit 4.12 or higher, or TestNG
6.14.3 or higher.
+ Since 3.6.0, all test frameworks run via the unified JUnit Platform provider.
Notices
@@ -80,6 +64,6 @@ Other features
* Re-run and skip execution
Since of 2.19.1 you can use parameters <<<skipAfterFailureCount>>> and
<<<rerunFailingTestsCount>>> together.
- This is enabled by providers <<<surefire-junit4>>> and
<<<surefire-junit47>>>. You can run again failed tests
- and skip the rest of the test-set if errors or failures reached
<<<skipAfterFailureCount>>>.
+ You can run again failed tests and skip the rest of the test-set if errors
or failures
+ reached <<<skipAfterFailureCount>>>.
Notice that failed tests within re-run phase are not included in
<<<skipAfterFailureCount>>>.
diff --git a/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
b/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
index 4a6b593d2..0252a050c 100644
--- a/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/examples/testng.apt.vm
@@ -214,7 +214,7 @@ Using TestNG
You can implement TestNG listener interface <<<org.testng.ITestListener>>> in
a separate test artifact <<<your-testng-listener-artifact>>> with
scope=test, or in project test source code
<<<src/test/java>>>. You can filter test artifacts by the parameter
<<<dependenciesToScan>>> to load its classes
- in current ClassLoader of surefire-testng provider. The TestNG reporter
class should implement <<<org.testng.IReporter>>>.
+ in current ClassLoader of the test provider. The TestNG reporter class
should implement <<<org.testng.IReporter>>>.
* The level of verbosity
diff --git a/maven-surefire-plugin/src/site/apt/history.apt.vm
b/maven-surefire-plugin/src/site/apt/history.apt.vm
index 014c9ae7c..c8b83a1a4 100644
--- a/maven-surefire-plugin/src/site/apt/history.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/history.apt.vm
@@ -36,7 +36,7 @@ Maven ${thisPlugin} Plugin
*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
||Versions ||Release Targets
\ |
*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| | Unified test execution via
JUnit Platform. Removed JUnit 3 provider. JUnit 4.12+ required (via Vintage
Engine). TestNG 6.14.3+ required. Stack trace memory optimization. \ |
+| | Unified test execution via
JUnit Platform. Removed JUnit 3 provider. JUnit 4.12+ required (via Vintage
Engine). TestNG 6.14.3+ required. Reimplemented stack trace handling. \ |
| 3.6.0 |
\ |
| |
{{{https://issues.apache.org/jira/issues/?jql=project%20%3D%20SUREFIRE%20AND%20fixVersion%20%3D%203.6.0%20ORDER%20BY%20priority%20DESC%2C%20key}See
the Release Notes for 3.6.0}} \ |
*---------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/maven-surefire-plugin/src/site/apt/index.apt.vm
b/maven-surefire-plugin/src/site/apt/index.apt.vm
index 6217ebfe3..7d3476b9f 100644
--- a/maven-surefire-plugin/src/site/apt/index.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/index.apt.vm
@@ -139,8 +139,6 @@ mvn verify
* {{{./examples/junit.html}Using JUnit}}
- * {{{./examples/pojo-test.html}Using POJO Tests}}
-
* {{{./examples/skipping-tests.html}Skipping Tests}}
* {{{./examples/skip-after-failure.html}Skip After Failure}}
@@ -169,6 +167,6 @@ mvn verify
* {{{./java9.html}Run tests with Java 9}}
- * {{{./docker.html}Run tests in Docker}}
+ * {{{./whats-new-3-6-0.html}What's New in 3.6.0}}
[]
diff --git a/maven-surefire-plugin/src/site/apt/usage.apt.vm
b/maven-surefire-plugin/src/site/apt/usage.apt.vm
index 78475bee2..7845d05ee 100644
--- a/maven-surefire-plugin/src/site/apt/usage.apt.vm
+++ b/maven-surefire-plugin/src/site/apt/usage.apt.vm
@@ -106,8 +106,6 @@ mvn verify
* JUnit (4.12+ or 5.x)
- * POJO
-
Since Surefire 3.6.0, all tests run via the JUnit Platform. The appropriate
engine is automatically selected
based on your dependencies:
@@ -122,20 +120,11 @@ mvn verify
Since the test framework dependency is required to compile the test classes
anyway, no additional configuration is required.
Note that any normal Surefire integration works identically no matter which
- providers are in use - so you can still produce a Cobertura report and a
+ test framework is in use - so you can still produce a Cobertura report and a
Surefire results report on your project web site for your TestNG tests,
for example.
- The POJO provider above allows you to write tests that do not depend on
either of
- JUnit and TestNG. It behaves in the same way, running all <<<test*>>>
methods that are
- public in the class, but the API dependency is not required. To perform
- assertions, the JDK 1.4 <<<assert>>> keyword can be used.
- See {{{./examples/pojo-test.html} Using POJO Tests}} for more information.
-
- All of the providers support the Surefire Plugin parameter configurations.
- However, there are additional options available if you are running TestNG
- tests (including if you are using TestNG to execute your JUnit tests, which
- occurs by default if both are present in Surefire).
+ There are additional options available if you are running TestNG tests.
See {{{./examples/testng.html} Using TestNG}} for more information.
diff --git a/maven-surefire-plugin/src/site/fml/faq.fml
b/maven-surefire-plugin/src/site/fml/faq.fml
index f1fca38af..d56c1af47 100644
--- a/maven-surefire-plugin/src/site/fml/faq.fml
+++ b/maven-surefire-plugin/src/site/fml/faq.fml
@@ -165,11 +165,11 @@ under the License.
<answer>
<p>
Surefire and Failsafe plugin may kill forked Surefire JVM when the
standard-input stream is closed.
- This works when you stop Maven process by CTRL+C but it is not
guaranteed on all platforms and this mechanism
- will be removed after the version 3.0.0-M5 (setup of TCP sockets for
interprocess communication).
- The Surefire and Failsafe 3.0.0-M4 disabled mechanism PINGing parent
process and natively killing mechanism.
- In order to enable these mechanisms, see the documentation of the
configuration parameter
- "enableProcessChecker" and enable these mechanisms. These mechanisms
have some drawbacks regarding your
+ This works when you stop Maven process by CTRL+C but it is not
guaranteed on all platforms.
+ Since version 3.0.0-M5, TCP/IP sockets are used for interprocess
communication.
+ See the documentation of the configuration parameter
+ "enableProcessChecker" for mechanisms to detect and kill orphan
forked JVMs.
+ These mechanisms have some drawbacks regarding your
OS systems and GC, therefore see the documentation for the parameter
"enableProcessChecker".
</p>
</answer>
diff --git a/maven-surefire-plugin/src/site/markdown/architecture.md
b/maven-surefire-plugin/src/site/markdown/architecture.md
index f29d36ba9..015693323 100644
--- a/maven-surefire-plugin/src/site/markdown/architecture.md
+++ b/maven-surefire-plugin/src/site/markdown/architecture.md
@@ -30,7 +30,7 @@ Apache Maven Surefire is the test execution framework for
Maven. It ships three
| **maven-failsafe-plugin** | Runs integration tests during `integration-test`
/ `verify` phases |
| **maven-surefire-report-plugin** | Generates HTML test reports from XML
results |
-Surefire supports JUnit 3, JUnit 4, JUnit 5 (Jupiter), TestNG, and plain POJO
tests. <br/>
+Surefire supports JUnit 4 (4.12+), JUnit 5/6 (Jupiter), and TestNG (6.14.3+).
<br/>
Until 3.5.x, each type was executed via a dedicated provider module. From
3.6.0 on, there is only one unified provider. <br/>
Tests execute in a **forked JVM** that communicates results back to Maven
through a binary event stream protocol.
@@ -82,10 +82,6 @@ graph TD
SRP["surefire-report-parser"]
end
- subgraph "Filtering"
- SG["surefire-grouper<br/><i>JavaCC category expression parser</i>"]
- end
-
MSP --> MSC
MFP --> MSC
MSC --> SA
@@ -443,16 +439,16 @@ The `maven-surefire-report-plugin` reads the XML files
(via `surefire-report-par
## Group / Category Filtering
-The `surefire-grouper` module provides test filtering by JUnit 4 categories or
TestNG groups.
+Since 3.6.0, test filtering by groups, categories, or tags is handled via the
JUnit Platform's native **tag expression** syntax.
### How it works
1. Users configure `<groups>` and `<excludedGroups>` in the plugin
configuration
-2. For **JUnit 4.7+**: the `surefire-junit47` provider uses
`GroupMatcherCategoryFilter` to filter tests by `@Category` annotations
-3. For **TestNG**: groups are passed directly to TestNG's native group
filtering
-4. For **JUnit Platform**: tag filter expressions are passed to the JUnit
Platform Launcher
+2. For **JUnit 4**: `@Category` annotations are mapped to JUnit Platform tags
via the Vintage Engine
+3. For **TestNG**: groups are mapped to JUnit Platform tags via the TestNG
Engine
+4. For **JUnit 5/6**: `@Tag` annotations are used natively
-The module includes a **JavaCC-generated parser** (`category-expression.jj`)
that parses boolean expressions over group names (e.g., `"fast AND NOT slow"`),
producing a `GroupMatcher` tree (`AndGroupMatcher`, `OrGroupMatcher`,
`InverseGroupMatcher`, `SingleGroupMatcher`).
+Tag filter expressions are passed directly to the JUnit Platform Launcher.
---
diff --git a/maven-surefire-plugin/src/site/markdown/docker.md
b/maven-surefire-plugin/src/site/markdown/docker.md
deleted file mode 100644
index b7235b267..000000000
--- a/maven-surefire-plugin/src/site/markdown/docker.md
+++ /dev/null
@@ -1,97 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-Build Docker image and run tests
-========================
-
-In current `.` directory is your project which starts with root POM.
-
-(including `.` at the end of next line)
-
-For Windows/macOS Users:
-
- $ docker build --no-cache -t my-image:1 -f ./Dockerfile .
- $ docker run -it --rm my-image:1 /bin/sh
-
-For Linux Users:
-
- $ sudo docker build --no-cache -t my-image:1 -f ./Dockerfile .
- $ sudo docker run -it --rm my-image:1 /bin/sh
-
-Run the command `mvn test` in the shell console of docker.
-
-Dockerfile in current directory
-========================
-
- FROM maven:3.5.3-jdk-8-alpine
- COPY ./. /
-
-The test
-========================
-
-Location in current directory.
-
- src/test/java/MyTest.java
-
-Simple test waiting 3 seconds:
-
- import org.junit.Test;
-
- public class MyTest {
- @Test
- public void test() throws InterruptedException {
- Thread.sleep(3000L);
- }
- }
-
-
-POM
-========================
-
-The `pom.xml`:
-
- <?xml version="1.0" encoding="UTF-8"?>
- <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
http://maven.apache.org/xsd/maven-4.0.0.xsd";>
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>x</groupId>
- <artifactId>y</artifactId>
- <version>1.0</version>
-
- <dependencies>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.13.2</version>
- </dependency>
- </dependencies>
-
- <build>
- <plugins>
- <plugin>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>latest plugin version here</version>
- </plugin>
- </plugins>
- </build>
-
- </project>
-
diff --git a/maven-surefire-plugin/src/site/markdown/whats-new-3-6-0.md
b/maven-surefire-plugin/src/site/markdown/whats-new-3-6-0.md
new file mode 100644
index 000000000..3a50290f1
--- /dev/null
+++ b/maven-surefire-plugin/src/site/markdown/whats-new-3-6-0.md
@@ -0,0 +1,175 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# What's New in Surefire 3.6.0
+
+## Overview
+
+Apache Maven Surefire 3.6.0 introduces a **major architectural
simplification**: all test frameworks now execute
+through a single unified [JUnit
Platform](https://junit.org/junit5/docs/current/user-guide/#overview-what-is-junit-5)
+provider (`surefire-junit-platform`). The five legacy providers have been
removed, reducing maintenance complexity
+and enabling a consistent experience across JUnit 5, JUnit 4, and TestNG.
+
+This page summarizes the key changes and provides a migration guide for users
upgrading from Surefire 3.5.x.
+
+## Unified Provider Architecture
+
+Starting with 3.6.0, **one provider runs all tests**:
+
+| Test Framework | Execution Engine | Minimum Version |
+|----------------|------------------|-----------------|
+| **JUnit 5** (Jupiter) | Jupiter Engine (native) | 5.x |
+| **JUnit 4** | [Vintage
Engine](https://junit.org/junit5/docs/current/user-guide/#migrating-from-junit4-running)
| **4.12** |
+| **JUnit 3** tests | Vintage Engine (via JUnit 4 compatibility) | Requires
JUnit **4.12**+ dependency |
+| **TestNG** | [TestNG JUnit Platform
Engine](https://github.com/junit-team/testng-engine) | **6.14.3** |
+
+No explicit provider configuration is needed — Surefire auto-detects which
engines are on the classpath
+and delegates accordingly.
+
+### Benefits
+
+- **Single codebase** to maintain for listener, reporter, and launcher logic
(previously 5 separate implementations)
+- **Consistent behavior** across all test frameworks for filtering, parallel
execution, and reporting
+- **Easier contributions** — new features only need to be implemented once
+
+## Breaking Changes
+
+### Removed Providers
+
+The following legacy provider modules have been removed:
+
+- `surefire-junit3`
+- `surefire-junit4`
+- `surefire-junit47`
+- `surefire-testng`
+
+Only one provider module remains: `surefire-junit-platform` (the unified
provider).
+
+### Minimum Version Requirements
+
+| Dependency | Minimum Version | Previous Minimum |
+|------------|----------------|------------------|
+| JUnit 4 | **4.12** | 3.8.1 |
+| TestNG | **6.14.3** | 5.x |
+
+- **JUnit 3**: No longer supported as a standalone dependency. JUnit 3 test
code can still run, but requires
+ a JUnit 4.12+ dependency on the classpath (the Vintage Engine handles the
execution).
+- **JUnit 4 versions before 4.12** are no longer supported.
+- **TestNG versions before 6.14.3** are no longer supported.
+
+### Reimplemented Stack Trace Handling
+
+Stack trace handling has been completely reimplemented as part of the provider
unification. The previous
+per-provider implementations (`LegacyPojoStackTraceWriter`,
`JUnit4StackTraceWriter`) have been replaced
+by a new `StackTraceProvider` and `DefaultStackTraceWriter` that work
uniformly across all test frameworks.
+The new implementation includes configurable frame filtering and truncation.
+
+## Migration Guide
+
+### JUnit 5/6 Users
+
+**No changes needed.** Your tests already run on the JUnit Platform natively.
+
+### JUnit 4 Users (4.12+)
+
+**No changes needed** in most cases. Surefire automatically adds the Vintage
Engine and routes your tests
+through the JUnit Platform. Verify your JUnit 4 dependency is version **4.12
or later**:
+
+```xml
+<dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.13.2</version>
+ <scope>test</scope>
+</dependency>
+```
+
+### JUnit 3 Users
+
+Add or update to a JUnit 4.12+ dependency. Your JUnit 3 test code will
continue to run unchanged
+via the Vintage Engine:
+
+```xml
+<dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.13.2</version>
+ <scope>test</scope>
+</dependency>
+```
+
+### TestNG Users
+
+Ensure your TestNG version is **6.14.3 or later**. Surefire will automatically
use the
+[TestNG JUnit Platform Engine](https://github.com/junit-team/testng-engine) to
execute your tests:
+
+```xml
+<dependency>
+ <groupId>org.testng</groupId>
+ <artifactId>testng</artifactId>
+ <version>7.10.2</version>
+ <scope>test</scope>
+</dependency>
+```
+
+TestNG configuration (groups, listeners, suites, etc.) continues to work
through Surefire's plugin
+configuration and is mapped to the JUnit Platform infrastructure.
+
+The `suiteXmlFiles` configuration for TestNG is no longer supported. You must
now use groups or Junit suite support
+
+
+
+### Staying on Surefire 3.5.x
+
+If you cannot update your test dependencies, you can stay on the 3.5.x line:
+
+```xml
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>3.5.5</version>
+</plugin>
+```
+
+### Transitional: Using a Legacy Provider with 3.6.0
+
+As a transitional measure, you can add a legacy provider from the 3.5.x line
as a plugin dependency:
+
+```xml
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>3.6.0</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven.surefire</groupId>
+ <artifactId>surefire-junit4</artifactId>
+ <version>3.5.5</version>
+ </dependency>
+ </dependencies>
+</plugin>
+```
+
+Note: this backward compatibility may not be maintained in future releases.
+
+## Further Reading
+
+- [Provider Selection](examples/providers.html) — Details on the unified
provider and legacy provider selection
+- [Architecture Overview](architecture.html) — In-depth architecture
documentation
+- [PR #3179](https://github.com/apache/maven-surefire/pull/3179) — The primary
pull request implementing the unified provider
diff --git a/maven-surefire-plugin/src/site/site.xml
b/maven-surefire-plugin/src/site/site.xml
index 9da393935..f11406a53 100644
--- a/maven-surefire-plugin/src/site/site.xml
+++ b/maven-surefire-plugin/src/site/site.xml
@@ -25,12 +25,12 @@
<body>
<menu name="Overview">
<item name="Introduction" href="index.html"/>
+ <item name="What's New in 3.6.0" href="whats-new-3-6-0.html"/>
<item name="Plugin Documentation" href="plugin-info.html"/>
<item name="Usage" href="usage.html"/>
<item name="API" href="api.html"/>
<item name="FAQ" href="faq.html"/>
<item name="Overall Archive" href="architecture.html"/>
- <item name="Unified Providers changes" href="pr-3179-unified-provider"/>
<item name="Developing" href="developing.html"/>
<!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
<item name="License" href="http://www.apache.org/licenses/"/>
@@ -62,7 +62,6 @@
<item name="Using Console Logs" href="examples/logging.html"/>
<item name="Shutdown of Forked JVM" href="examples/shutdown.html"/>
<item name="Run tests with Java 9" href="java9.html"/>
- <item name="Run tests in Docker" href="docker.html"/>
<item name="Run tests in a different JVM using toolchains"
href="examples/toolchains.html"/>
</menu>
</body>
diff --git a/surefire-api/src/site/apt/index.apt
b/surefire-api/src/site/apt/index.apt
index f83f0ba7e..50f4c9eef 100644
--- a/surefire-api/src/site/apt/index.apt
+++ b/surefire-api/src/site/apt/index.apt
@@ -43,8 +43,6 @@ Surefire API
* TestNG XML test suite: this constructs a single suite from a
<<<testng.xml>>> file. The definitions inside the file will match those above.
- * JUnit 3.x: Groups are not supported.
-
[]
See {{{../surefire-providers/index.html}Surefire Providers}} for more
information on specific providers.
