You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@maven.apache.org by "olamy (via GitHub)" <gi...@apache.org> on 2026/03/25 03:59:51 UTC
[PR] Fix documentation due to code simplification with providers [maven-surefire]
olamy opened a new pull request, #3332:
URL: https://github.com/apache/maven-surefire/pull/3332
Signed-off-by: Olivier Lamy <ol...@apache.org>
Following this checklist to help us incorporate your
contribution quickly and easily:
- [ ] Each commit in the pull request should have a meaningful subject line and body.
- [ ] Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
- [ ] Run `mvn clean install` to make sure basic checks pass. A more thorough check will
be performed on your pull request automatically.
- [ ] You have run the integration tests successfully (`mvn -Prun-its clean install`).
If your pull request is about ~20 lines of code you don't need to sign an
[Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf) if you are unsure
please ask on the developers list.
To make clear that you license your contribution under
the [Apache License Version 2.0, January 2004](http://www.apache.org/licenses/LICENSE-2.0)
you have to acknowledge this by using the following check-box.
- [ ] I hereby declare this contribution to be licenced under the [Apache License Version 2.0, January 2004](http://www.apache.org/licenses/LICENSE-2.0)
- [ ] In any other case, please file an [Apache Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix documentation due to code simplification with providers [maven-surefire]
Posted by "slawekjaranowski (via GitHub)" <gi...@apache.org>.
slawekjaranowski commented on PR #3332:
URL: https://github.com/apache/maven-surefire/pull/3332#issuecomment-4148078129
one fix after look at rendered docs
- #3337
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix documentation due to code simplification with providers [maven-surefire]
Posted by "olamy (via GitHub)" <gi...@apache.org>.
olamy commented on code in PR #3332:
URL: https://github.com/apache/maven-surefire/pull/3332#discussion_r3007496648
##########
maven-surefire-plugin/src/site/markdown/whats-new-3-6-0.md:
##########
@@ -0,0 +1,171 @@
+<!--
+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
Review Comment:
good point. fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix documentation due to code simplification with providers [maven-surefire]
Posted by "slawekjaranowski (via GitHub)" <gi...@apache.org>.
slawekjaranowski commented on code in PR #3332:
URL: https://github.com/apache/maven-surefire/pull/3332#discussion_r3004803004
##########
maven-surefire-plugin/src/site/markdown/whats-new-3-6-0.md:
##########
@@ -0,0 +1,171 @@
+<!--
+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
Review Comment:
I would like add info about not supporting `suiteXmlFile` for TestNG.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix documentation due to code simplification with providers [maven-surefire]
Posted by "olamy (via GitHub)" <gi...@apache.org>.
olamy commented on PR #3332:
URL: https://github.com/apache/maven-surefire/pull/3332#issuecomment-4147747211
@sparsick thanks for the review.
@sebtiem
@slawekjaranowski
I have added a dedicated page called " What's New in Surefire 3.6.0" please have a look
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix documentation due to code simplification with providers [maven-surefire]
Posted by "olamy (via GitHub)" <gi...@apache.org>.
olamy commented on code in PR #3332:
URL: https://github.com/apache/maven-surefire/pull/3332#discussion_r3004633710
##########
maven-surefire-plugin/src/site/markdown/architecture.md:
##########
@@ -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**: `@Tag` annotations are used natively
Review Comment:
fixed bee6ce4c07709a5a86c585f7653f49c82878bd98
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix documentation due to code simplification with providers [maven-surefire]
Posted by "sparsick (via GitHub)" <gi...@apache.org>.
sparsick commented on code in PR #3332:
URL: https://github.com/apache/maven-surefire/pull/3332#discussion_r2987651813
##########
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 (Jupiter), and TestNG (6.14.3+). <br/>
Review Comment:
We should mention JUnit 6 explicitly, like JUnit5/6
##########
maven-surefire-plugin/src/site/markdown/architecture.md:
##########
@@ -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**: `@Tag` annotations are used natively
Review Comment:
We should mention JUnit 6 explicitly, like `JUnit5/6`
##########
maven-surefire-plugin/src/site/apt/developing.apt.vm:
##########
@@ -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, TestNG 6.14.3+) are executed via the JUnit Platform provider.
Review Comment:
We should mention JUnit 6 explicitly, like JUnit5/6
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix documentation due to code simplification with providers [maven-surefire]
Posted by "olamy (via GitHub)" <gi...@apache.org>.
olamy commented on code in PR #3332:
URL: https://github.com/apache/maven-surefire/pull/3332#discussion_r3004633444
##########
maven-surefire-plugin/src/site/apt/developing.apt.vm:
##########
@@ -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, TestNG 6.14.3+) are executed via the JUnit Platform provider.
Review Comment:
fixed bee6ce4c07709a5a86c585f7653f49c82878bd98
##########
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 (Jupiter), and TestNG (6.14.3+). <br/>
Review Comment:
fixed bee6ce4c07709a5a86c585f7653f49c82878bd98
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix documentation due to code simplification with providers [maven-surefire]
Posted by "olamy (via GitHub)" <gi...@apache.org>.
olamy merged PR #3332:
URL: https://github.com/apache/maven-surefire/pull/3332
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@maven.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org