### Example Include Patterns

Source: https://maven.apache.org/surefire/maven-surefire-plugin/xref/org/apache/maven/plugin/surefire/SurefireMojo.html

Demonstrates various include patterns, including path-based, simple file names, regex, and method filtering.

```plaintext
*\/test\/*
**\/NotIncludedByDefault.java
%regex[.*Test.*|.*Not.*]
pkg.SomeTest#testMethod
```

--------------------------------

### Define JDK 9 in toolchains.xml

Source: https://maven.apache.org/surefire/maven-surefire-plugin/java9.html

Example of defining a JDK 9 toolchain entry in the toolchains.xml file.

```xml
<toolchains xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 https://maven.apache.org/xsd/toolchains-1.1.0.xsd">
  <toolchain>
    <type>jdk</type>
    <provides>
      <version>9</version>
      <vendor>oracle</vendor>
      <id>jdk9</id>
    </provides>
    <configuration>
      <jdkHome>/path/to/jdk9</jdkHome>
    </configuration>
  </toolchain>
</toolchains>
```

--------------------------------

### Example Exclude Patterns

Source: https://maven.apache.org/surefire/maven-surefire-plugin/xref/org/apache/maven/plugin/surefire/SurefireMojo.html

Demonstrates various exclude patterns, including path-based, simple file names, regex, and method filtering.

```plaintext
*\/test\/*
**\/DontRunTest.*
%regex[.*Test.*|.*Not.*]
pkg.SomeTest#testMethod
```

--------------------------------

### Basic Java Classpath Execution

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/class-loading.html

This is a basic example of how to launch a Java application with a specified classpath. It may encounter command-line length limitations on some operating systems.

```bash
java -classpath foo.jar:bar.jar MyApp
```

--------------------------------

### Base Directory Methods

Source: https://maven.apache.org/surefire/maven-surefire-plugin/apidocs/org/apache/maven/plugin/surefire/SurefireMojo.html

Methods for getting and setting the base directory for the project.

```APIDOC
## getBasedir

### Description
Gets the base directory of the project.

### Method
`public File getBasedir()`

### Inherited From
`SurefireExecutionParameters`, `SurefireReportParameters`
```

```APIDOC
## setBasedir

### Description
Sets the base directory for the project.

### Method
`public void setBasedir(File basedir)`

### Parameters
* **basedir** (File) - The base directory.

### Inherited From
`SurefireExecutionParameters`, `SurefireReportParameters`
```

--------------------------------

### Example 1-Line Error Summary Output

Source: https://maven.apache.org/surefire/maven-surefire-plugin/newerrorsummary.html

This is an example of the compact one-line error summary format introduced in Surefire 2.13. It highlights assertion failures and errors, with specific symbols indicating nested exceptions.

```text
Failures:
  Test1.assertion1:59 Bending maths expected:<[123]> but was:<[312]>
  Test1.assertion2:64 True is false

Errors:
  Test1.nullPointerInLibrary:38 » NullPointer
  Test1.failInMethod:43->innerFailure:68 NullPointer Fail here
  Test1.failInLibInMethod:48 » NullPointer
  Test1.failInNestedLibInMethod:54->nestedLibFailure:72 » NullPointer
  Test2.test6281:33 Runtime FailHere

```

--------------------------------

### Unsupported Java Version Exception

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/toolchains.html

Example of the UnsupportedClassVersionError that occurs when the selected toolchain version is lower than the minimum required by the Surefire Booter.

```text
Exception in thread "main" java.lang.UnsupportedClassVersionError: org/apache/maven/surefire/booter/ForkedBooter: Unsupported major.minor version 52.0
        at java.lang.ClassLoader.defineClass1(Native Method)
        at java.lang.ClassLoader.defineClass(ClassLoader.java:800)
        at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)
        at java.net.URLClassLoader.defineClass(URLClassLoader.java:449)
        at java.net.URLClassLoader.access$100(URLClassLoader.java:71)
        at java.net.URLClassLoader$1.run(URLClassLoader.java:361)
        at java.net.URLClassLoader$1.run(URLClassLoader.java:355)
        at java.security.AccessController.doPrivileged(Native Method)
        at java.net.URLClassLoader.findClass(URLClassLoader.java:354)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:425)
        at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:308)
        at java.lang.ClassLoader.loadClass(ClassLoader.java:358)
        at sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:482)
```

--------------------------------

### Manifest-Only JAR Classpath Execution

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/class-loading.html

This example demonstrates launching an application using a manifest-only JAR. The JAR's manifest file specifies additional JARs to be included in the classpath, simulating a more realistic environment.

```bash
java -classpath booter.jar MyApp
```

--------------------------------

### Clone Maven Surefire Plugin Repository (Anonymous Access)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/scm.html

Use this command to check out the source code anonymously from Git. Ensure you have Git installed.

```bash
git clone --branch surefire-3.6.0-M1 https://github.com/apache/maven-surefire.git
```

--------------------------------

### Include Patterns from a File for Surefire Plugin

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Specify include patterns in a file, with each pattern on a new line. Blank lines and lines starting with '#' are ignored. This can be used in conjunction with the `includes` parameter.

```plaintext
*/test/*
**/NotIncludedByDefault.java
%regex[.*Test.*|.*Not.*]
```

--------------------------------

### Configure JUnit 5 Reporters in Maven Surefire

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit-platform.html

Configure default JUnit 5 reporters for the Maven Surefire plugin. This example shows how to customize stateless and console output reporters.

```xml
<build>
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.6.0-M1</version>
            <configuration>
                <statelessTestsetReporter implementation="org.apache.maven.plugin.surefire.extensions.junit5.JUnit5Xml30StatelessReporter">
                    <disable>false</disable>
                    <version>3.0.2</version>
                    <usePhrasedFileName>false</usePhrasedFileName>
                    <usePhrasedTestSuiteClassName>true</usePhrasedTestSuiteClassName>
                    <usePhrasedTestCaseClassName>true</usePhrasedTestCaseClassName>
                    <usePhrasedTestCaseMethodName>true</usePhrasedTestCaseMethodName>
                </statelessTestsetReporter>
                <consoleOutputReporter implementation="org.apache.maven.plugin.surefire.extensions.junit5.JUnit5ConsoleOutputReporter">
                    <disable>false</disable>
                    <encoding>UTF-8</encoding>
                    <usePhrasedFileName>false</usePhrasedFileName>
                </consoleOutputReporter>
                <statelessTestsetInfoReporter implementation="org.apache.maven.plugin.surefire.extensions.junit5.JUnit5StatelessTestsetInfoReporter">
                    <disable>false</disable>
                    <usePhrasedFileName>false</usePhrasedFileName>
                    <usePhrasedClassNameInRunning>true</usePhrasedClassNameInRunning>
                    <usePhrasedClassNameInTestCaseSummary>true</usePhrasedClassNameInTestCaseSummary>
                </statelessTestsetInfoReporter>
            </configuration>
        </plugin>
    </plugins>
</build>
```

--------------------------------

### Include Patterns File

Source: https://maven.apache.org/surefire/maven-surefire-plugin/xref/org/apache/maven/plugin/surefire/SurefireMojo.html

Specifies a file containing include patterns for tests. Blank lines and lines starting with '#' are ignored. Supports path, simple, regex, and method filtering.

```java
@Parameter(property = "surefire.includesFile")
    private File includesFile;
```

--------------------------------

### Configure Forked Test Execution with Surefire Plugin

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/fork-options-and-parallel-execution.html

Configure the Surefire plugin to use up to three forked processes for test execution. Each process is passed specific JVM arguments, a unique database schema, and a distinct working directory. This setup ensures isolation and allows for dynamic configuration based on the fork number.

```xml
<plugins>
  ...
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.6.0-M1</version>
    <configuration>
        <forkCount>3</forkCount>
        <reuseForks>true</reuseForks>
        <argLine>-Xmx1024m -XX:MaxPermSize=256m</argLine>
        <systemPropertyVariables>
            <databaseSchema>MY_TEST_SCHEMA_${surefire.forkNumber}</databaseSchema>
        </systemPropertyVariables>
        <workingDirectory>FORK_DIRECTORY_${surefire.forkNumber}</workingDirectory>
    </configuration>
  </plugin>
...
</plugins>
```

--------------------------------

### Run Sample Project for Issue Demonstration

Source: https://maven.apache.org/surefire/maven-surefire-plugin/developing.html

Navigate to a sample project and run it to demonstrate an issue, specifying the Surefire version.

```bash
cd surefire-its/src/test/resources/failsafe-buildfail
mvn -Dsurefire.version=2.12 verify
```

--------------------------------

### Get Test Method

Source: https://maven.apache.org/surefire/maven-surefire-plugin/apidocs/org/apache/maven/plugin/surefire/SurefireMojo.html

Retrieves the name of the specific test to run.

```APIDOC
## getTest

### Description
Gets the name of the specific test to execute.

### Method
`public String getTest()`

### Inherited From
`SurefireExecutionParameters`
```

--------------------------------

### Display Surefire Plugin Help

Source: https://maven.apache.org/surefire/maven-surefire-plugin/plugin-info.html

Use this command to display help information for the Surefire plugin. Add '-Ddetail=true -Dgoal=<goal-name>' to see parameter details for a specific goal.

```bash
mvn surefire:help -Ddetail=true -Dgoal=<goal-name>
```

--------------------------------

### Getting Directory Scanner (Prior to 2.12.2)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/api.html

In versions prior to 2.12.2, providers obtained the DirectoryScanner directly from ProviderParameters.

```java
1.     directoryScanner = booterParameters.getDirectoryScanner();
2.     final TestsToRun scanResult = directoryScanner.locateTestClasses( testClassLoader, testChecker );
```

--------------------------------

### Main Build Path Method

Source: https://maven.apache.org/surefire/maven-surefire-plugin/apidocs/org/apache/maven/plugin/surefire/SurefireMojo.html

Method for setting the main build path.

```APIDOC
## setMainBuildPath

### Description
Sets the main build path.

### Method
`public void setMainBuildPath(File mainBuildPath)`

### Parameters
* **mainBuildPath** (File) - The main build path.

### Inherited From
`SurefireExecutionParameters`
```

--------------------------------

### Process Checker and Fork Node

Source: https://maven.apache.org/surefire/maven-surefire-plugin/xref/org/apache/maven/plugin/surefire/SurefireMojo.html

Get the enable process checker status and the fork node factory. These are protected methods for internal plugin use.

```java
    @Override
    protected final String getEnableProcessChecker() {
        return enableProcessChecker;
    }

    @Override
    protected final ForkNodeFactory getForkNode() {
        return forkNode;
    }
```

--------------------------------

### Use System ClassLoader Configuration

Source: https://maven.apache.org/surefire/maven-surefire-plugin/xref/org/apache/maven/plugin/surefire/SurefireMojo.html

Option to pass dependencies to the system's classloader instead of using an isolated classloader when forking. Defaults to true.

```java
@Parameter(property = "surefire.useSystemClassLoader", defaultValue = "true")
    private boolean useSystemClassLoader;
```

--------------------------------

### Maven Build and Test Commands

Source: https://maven.apache.org/surefire/maven-surefire-plugin/architecture.html

Common Maven commands for building and testing projects. Use these for full builds, module-specific builds, or running individual tests.

```bash
mvn clean install

mvn clean install -P run-its

mvn clean install -pl surefire-booter

mvn test -pl surefire-booter -Dtest=ForkedBooterTest

mvn verify -pl surefire-its -Prun-its -Dit.test=JUnit47RedirectOutputIT

mvn install -P ide-development -f surefire-shared-utils/pom.xml
mvn compile -f surefire-grouper/pom.xml
```

--------------------------------

### Help Mojo

Source: https://maven.apache.org/surefire/maven-surefire-plugin/apidocs/org/apache/maven/plugins/maven_surefire_plugin/HelpMojo.html

Displays help information about the Maven Surefire Plugin. You can invoke this goal using the Maven command line.

```APIDOC
## help

### Description
Display help information on maven-surefire-plugin.

### Method
Mojo

### Endpoint
N/A (Maven Plugin Goal)

### Parameters
#### Command Line Options
- `-Ddetail=true`: Displays detailed parameter information.
- `-Dgoal=<goal-name>`: Specifies the goal for which to display detailed help.

### Request Example
```bash
mvn surefire:help -Ddetail=true -Dgoal=run
```

### Response
N/A (Output is printed to the console)
```

--------------------------------

### Flaky Test Summary Example

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/rerun-failing-tests.html

After tests complete, a summary will include the count of flaky tests if any tests passed on a rerun. This indicates tests that are not consistently passing.

```text
1.   Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Flakes: 1
```

--------------------------------

### Help Mojo

Source: https://maven.apache.org/surefire/maven-surefire-plugin/apidocs/org/apache/maven/plugins/maven_surefire_plugin/package-summary.html

Display help information on the maven-surefire-plugin. You can call `mvn surefire:help -Ddetail=true -Dgoal=<goal-name>` to display parameter details for a specific goal.

```APIDOC
## GET /help

### Description
Display help information on the maven-surefire-plugin.

### Method
GET

### Endpoint
/help

### Query Parameters
- **detail** (boolean) - Optional - If true, displays detailed parameter information.
- **goal** (string) - Optional - The name of the goal for which to display detailed help.
```

--------------------------------

### Spock Parameterized Test with JUnit5

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/spock.html

Example of a parameterized test in Spock/Groovy. This test will execute multiple times with different input values defined in the 'where' block.

```groovy
import pkg.Calculator
import spock.lang.Specification

class CalculatorTest extends Specification
{
    def "Multiply: #a * #b = #expectedResult"() 
    {
        given: "Calculator"
        def calc = new Calculator()

        when: "multiply"
        def result = calc.multiply( a, b )

        then: "result is as expected"
        result == expectedResult
        println "result = ${result}"

        where:
        a  | b | expectedResult
        1  | 2 | 3
        -5 | 2 | -3
    }
}
```

--------------------------------

### Clone Surefire Repository

Source: https://maven.apache.org/surefire/maven-surefire-plugin/developing.html

Clone the complete Surefire module repository to build from.

```bash
git clone https://gitbox.apache.org/repos/asf/maven-surefire.git
```

--------------------------------

### Include Patterns in includesFile

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Specify include patterns for tests in a file. Supports simple paths, wildcards, and regex. Blank lines and lines starting with '#' are ignored.

```text
1.   2. */test/*
3. **/NotIncludedByDefault.java
4. %regex[.*Test.*|.*Not.*]
```

--------------------------------

### Configure JUnit5 Suite with Surefire Plugin

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit-platform.html

Set up JUnit Jupiter engine, the JUnit Platform suite engine, and configure the Maven Surefire Plugin to run JUnit5 suite tests.

```xml
<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter-engine</artifactId>
        <version>5.9.1</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.platform</groupId>
        <artifactId>junit-platform-suite-engine</artifactId>
        <version>1.9.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.6.0-M1</version>
            <configuration>
                <test><!-- your test suite class name should be here --></test>
            </configuration>
        </plugin>
    </plugins>
</build>
```

--------------------------------

### JUnit 4 Test Class with Categories

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit.html

Annotate test methods with JUnit 4 `@Category` annotations to group them. This example shows tests for `SlowTests`, `SlowerTests`, and `FastTests`.

```java
public class AppTest {
      @Test
      @Category(com.mycompany.SlowTests.class)
      public void testSlow() {
        System.out.println("slow");
      }
  
      @Test
      @Category(com.mycompany.SlowerTests.class)
      public void testSlower() {
        System.out.println("slower");
      }
  
      @Test
      @Category(com.mycompany.FastTests.class)
      public void testSlow() {
        System.out.println("fast");
      }
    }
```

--------------------------------

### Debug Forked Tests (Custom Port)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/debugging.html

Configure a different port for remote debugging by providing a detailed value to the `maven.surefire.debug` property. This example uses port 8000.

```bash
mvn -Dmaven.surefire.debug="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=localhost:8000" test
```

--------------------------------

### Configure Stateless Testset Info Reporter

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

No description provided in source. This parameter configures the stateless testset info reporter.

```xml
<configuration>
  <statelessTestsetInfoReporter/>
</configuration>
```

--------------------------------

### Locating and Ordering Test Classes (2.11 and later)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/api.html

Starting from version 2.11, providers must implement an additional step to order the test classes using the RunOrderCalculator.

```java
1.     TestsToRun scanned = directoryScanner.locateTestClasses( testClassLoader, scannerFilter );
2.     return providerParameters.getRunOrderCalculator().orderTestClasses(  scanned );
```

--------------------------------

### Getting Scan Result (2.12.2 and later)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/api.html

From version 2.12.2 onwards, ProviderParameters#getDirectoryScanner is deprecated. Providers should instead use getScanResult() to obtain the scan result and then apply filters.

```java
1.     scanResult = booterParameters.getScanResult();
2.     final TestsToRun testsToRun = scanResult.applyFilter(testChecker, testClassLoader );
```

--------------------------------

### Exclude Patterns File

Source: https://maven.apache.org/surefire/maven-surefire-plugin/xref/org/apache/maven/plugin/surefire/SurefireMojo.html

Specifies a file containing exclude patterns for tests. Blank lines and lines starting with '#' are ignored. Supports path, simple, regex, and method filtering.

```java
@Parameter(property = "surefire.excludesFile")
    private File excludesFile;
```

--------------------------------

### Configure Test JVM with jdkToolchain (Version and Vendor)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Configure the test JVM using Maven toolchains by specifying both the version and vendor. This provides more specific JVM selection.

```xml
7.    <configuration>
8.        ...
9.        <jdkToolchain>
10.            <version>1.8</version>
11.            <vendor>zulu</vendor>
12.        </jdkToolchain>
13.    </configuration>
```

--------------------------------

### Run Maven with specific toolchains file

Source: https://maven.apache.org/surefire/maven-surefire-plugin/java9.html

Execute Maven tests using a specific toolchains.xml file via the -t command line argument.

```bash
$ mvn -t /path/to/.m2/toolchains.xml test
```

--------------------------------

### Configure Stateless Testset Reporter

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

No description provided in source. This parameter configures the stateless testset reporter.

```xml
<configuration>
  <statelessTestsetReporter/>
</configuration>
```

--------------------------------

### Skip Tests via Command Line

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/skipping-tests.html

Execute Maven with the `-DskipTests` argument to skip running tests for the current build.

```bash
mvn install -DskipTests
```

--------------------------------

### JUnit 4 Test Suite Example

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/fork-options-and-parallel-execution.html

Define a JUnit 4 TestSuite class to group related test classes within a package. This is used by the Surefire plugin for parallel execution.

```java
package features.areaA;

import org.junit.runner.RunWith;
import org.junit.runners.Suite;

@RunWith(Suite.class)
@Suite.SuiteClasses({
    SomeTest.class,
    AnotherTest.class
})
public class TestSuite {
}
```

--------------------------------

### Transitional: Using Legacy Provider with Surefire 3.6.0

Source: https://maven.apache.org/surefire/maven-surefire-plugin/whats-new-3-6-0.html

As a transitional measure, you can add a legacy provider from the 3.5.x line as a plugin dependency to use Surefire 3.6.0 with older test frameworks. This backward compatibility may not be maintained in future releases.

```xml
  1. <plugin>
  2.     <groupId>org.apache.maven.plugins</groupId>
  3.     <artifactId>maven-surefire-plugin</artifactId>
  4.     <version>3.6.0</version>
  5.     <dependencies>
  6.         <dependency>
  7.             <groupId>org.apache.maven.surefire</groupId>
  8.             <artifactId>surefire-junit4</artifactId>
  9.             <version>3.5.5</version>
 10.         </dependency>
 11.     </dependencies>
 12. </plugin>
```

--------------------------------

### Configure JDK Toolchain for Testing (Version)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Use the `<jdkToolchain>` configuration to specify the desired JDK version for running tests, allowing for different JVMs than the build environment. This requires Maven 3.3.x or later.

```xml
<configuration>
    ...
    <jdkToolchain>
        <version>1.11</version>
    </jdkToolchain>
</configuration>
```

--------------------------------

### Configure Forked Process Exit Timeout

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Set `<forkedProcessExitTimeoutInSeconds>` to define the timeout in seconds for terminating a forked process. This is useful when tests start non-daemon threads. A negative value defaults to 30 seconds.

```xml
<forkedProcessExitTimeoutInSeconds> | int | 2.20 | Forked process is normally terminated without any significant delay after given tests have completed. If the particular tests started non-daemon Thread(s), the process hangs instead of been properly terminated by `System.exit()`. Use this parameter in order to determine the timeout of terminating the process. see the documentation: http://maven.apache.org/surefire/maven-surefire-plugin/examples/shutdown.html Turns to default fallback value of 30 seconds if negative integer.
```

--------------------------------

### Configure System Properties with systemProperties (Deprecated)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/system-properties.html

The deprecated systemProperties configuration allows setting system properties using a nested property structure. Note that only String typed properties can be passed; other types will be passed literally.

```xml
<project>
  [...] 
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.6.0-M1</version>
        <configuration>
          <systemProperties>
            <property>
              <name>propertyName</name>
              <value>propertyValue</value>
            </property>
            [...]
          </systemProperties>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
```

```xml
<project>
  [...] 
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.6.0-M1</version>
        <configuration>
          <systemProperties>
            <property>
              <name>buildDir</name>
              <value>${project.build.outputDirectory}</value>
            </property>
          </systemProperties>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
```

--------------------------------

### Integrate External JUnit 5 Tree Reporter in Maven Surefire

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit-platform.html

Integrate an external JUnit 5 tree reporter by adding its dependency and configuring the Surefire plugin. This example disables the default console output reporter.

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.6.0-M1</version>
    <dependencies>
        <dependency>
            <groupId>me.fabriciorby</groupId>
            <artifactId>maven-surefire-junit5-tree-reporter</artifactId>
            <version>0.1.0</version>
        </dependency>
    </dependencies>
    <configuration>
        <reportFormat>plain</reportFormat>
        <consoleOutputReporter>
            <disable>true</disable>
        </consoleOutputReporter>
        <statelessTestsetInfoReporter implementation="org.apache.maven.plugin.surefire.extensions.junit5.JUnit5StatelessTestsetInfoTreeReporter"/>
    </configuration>
</plugin>
```

--------------------------------

### Include JUnit Jupiter API and Vintage Engine Dependency

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit-platform.html

Configure dependencies to include the JUnit Jupiter API and the JUnit Vintage Engine. This setup allows running older JUnit tests alongside JUnit 5.

```xml
  1. <dependencies>
  2.     <dependency>
  3.         <groupId>org.junit.jupiter</groupId>
  4.         <artifactId>junit-jupiter-api</artifactId>
  5.         <version>5.9.1</version>
  6.         <scope>test</scope>
  7.     </dependency>
  8.     <dependency>
  9.         <groupId>org.junit.vintage</groupId>
  10.         <artifactId>junit-vintage-engine</artifactId>
  11.         <version>5.9.1</version>
  12.         <scope>test</scope>
  13.     </dependency>
  14. </dependencies>
```

--------------------------------

### Specify Excludes Using a File

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Use the 'excludesFile' parameter to provide a file containing exclude patterns. Blank lines and lines starting with '#' are ignored. Patterns from this file are appended if 'excludes' are also specified. This feature is available since version 2.13.

```plaintext
*/test/*
**/DontRunTest.*
%regex[.*Test.*|.*Not.*]
```

--------------------------------

### Configure Test Inclusion/Exclusion Patterns

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/inclusion-exclusion.html

Use fully qualified class names or package names with wildcard characters for flexible test selection. The '?' character matches a single character, and '*' matches zero or more characters. This syntax is applicable to parameters like 'test', 'includes', 'excludes', 'includesFile', and 'excludesFile'.

```xml
  1.   [...]
  2.           <include>my.package.*, another.package.*</include>
  3.   [...]
  4.           <exclude>my.package.???ExcludedTest, another.package.*ExcludedTest</exclude>
  5.   [...]
```

--------------------------------

### Run Methods Using Wildcard Patterns

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/single-test.html

You can use wildcard patterns with the '#methodName' syntax to run multiple methods matching the pattern within a test class.

```bash
mvn -Dtest=TestCircle#test* test
```

--------------------------------

### Configure JDK Toolchain for Testing (Version and Vendor)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Further refine JDK toolchain configuration by specifying both the version and vendor, useful for projects requiring specific JVM distributions. This requires Maven 3.3.x or later.

```xml
<configuration>
    ...
    <jdkToolchain>
        <version>1.8</version>
        <vendor>zulu</vendor>
    </jdkToolchain>
</configuration>
```

--------------------------------

### Specify JVM path in plugin configuration

Source: https://maven.apache.org/surefire/maven-surefire-plugin/java9.html

Directly point to the Java executable path in the plugin configuration. This approach is generally discouraged as it is not portable.

```xml
<configuration>
    <jvm>/path/to/jdk9/bin/java</jvm>
</configuration>
```

--------------------------------

### Use Manifest-Only JAR Configuration

Source: https://maven.apache.org/surefire/maven-surefire-plugin/xref/org/apache/maven/plugin/surefire/SurefireMojo.html

Forces Surefire to launch tests with a plain Java classpath instead of a manifest-only JAR. Defaults to true. Setting to false may cause issues on Windows with long classpaths.

```java
@Parameter(property = "surefire.useManifestOnlyJar", defaultValue = "true")
    private boolean useManifestOnlyJar;
```

--------------------------------

### getSystemPropertiesFile

Source: https://maven.apache.org/surefire/maven-surefire-plugin/apidocs/org/apache/maven/plugin/surefire/SurefireMojo.html

Retrieves the file containing system properties for the test execution.

```APIDOC
## getSystemPropertiesFile()

### Description

Gets the file that contains system properties to be used during test execution.

### Method

```java
public File getSystemPropertiesFile()
```

### Returns

A `File` object representing the system properties file.

### Specified by

`AbstractSurefireMojo.getSystemPropertiesFile`
```

--------------------------------

### Execute Tests with Maven

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/cucumber.html

Run the BDD scenarios during the test phase of the build lifecycle.

```bash
  1. mvn test
```

--------------------------------

### Complex Include Patterns for Surefire Plugin

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Use this syntax within the `<include>` tag to specify multiple inclusion patterns, including regex, wildcards, and exclusions. Patterns are relative to the test classes directory.

```xml
<include>%regex[.*[Cat|Dog].*], Basic????, !Unstable*</include>
```

```xml
<include>%regex[.*[Cat|Dog].*], !%regex[pkg.*Slow.*.class], pkg/**/*Fast*.java</include>
```

--------------------------------

### Run Tests Using Wildcard Patterns

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/single-test.html

You can use wildcard patterns with the 'test' parameter to run multiple tests that match the pattern.

```bash
mvn -Dtest=TestCi*le test
```

--------------------------------

### Append System Properties from Parent Configuration

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/system-properties.html

To inherit systemProperties from a parent configuration, use 'combine.children="append"' on the systemProperties node in the child POM.

```xml
<systemProperties combine.children="append">
    <property>
       [...]
    </property>
 </systemProperties>
```

--------------------------------

### Configure Custom Communication Channel Implementation

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/process-communication.html

Implement a custom communication channel by providing your own `ForkNodeFactory` and SPI implementation. Declare your extension API implementation as a dependency and specify its fully qualified class name in the plugin configuration.

```xml
<project>
    [...] 
    <dependencies>
        <dependency>
            <groupId>your-extension-spi-impl-groupid</groupId>
            <artifactId>your-extension-spi-impl-artifactid</artifactId>
            <version>your-extension-spi-impl-version</version>
        </dependency>
    </dependencies>
    [...] 
    <build>
        <plugins>
            [...] 
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.6.0-M1</version>
                <dependencies>
                    <dependency>
                        <groupId>your-extension-api-impl-groupid</groupId>
                        <artifactId>your-extension-api-impl-artifactid</artifactId>
                        <version>your-extension-api-impl-version</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <forkNode implementation="your.extention.api.impl.CustomForkNodeFactory"/>
                </configuration>
            </plugin>
            [...] 
        </plugins>
    </build>
    [...] 
</project>
```

--------------------------------

### Configure Fork Count for Parallel Execution

Source: https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html

Specify the number of VMs to fork in parallel using `<forkCount>`. Values like '1.5C' or '4' are accepted. '0' runs all tests in the main process. The `${surefire.forkNumber}` placeholder can be used in system properties and `argLine`.

```xml
<forkCount> | String | 2.14 | Option to specify the number of VMs to fork in parallel in order to execute the tests. When terminated with "C", the number part is multiplied with the number of CPU cores. Floating point value are only accepted together with "C". If set to "0", no VM is forked and all tests are executed within the main process.  
  
Example values: "1.5C", "4"   
  
The system properties and the `argLine` of the forked processes may contain the place holder string `${surefire.forkNumber}`, which is replaced with a fixed number for each of the parallel forks, ranging from **1** to the effective value of `forkCount` times the maximum number of parallel Surefire executions in maven parallel builds, i.e. the effective value of the **-T** command line argument of maven core.  
**Default** : `1`
```

--------------------------------

### Specify Tests Using Fully Qualified Names and Patterns

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/single-test.html

Use fully qualified class names or package structures with wildcards ('?' for single char, '*' for zero or more) within the '<test>' tag. Multiple formats can be combined.

```xml
<test>my.package.???Test#testMethod, another.package.*</test>
```

--------------------------------

### Attach Debugger to Surefire Fork

Source: https://maven.apache.org/surefire/maven-surefire-plugin/developing.html

Build the Surefire trunk and run tests with debugging enabled to attach a remote debugger to the Surefire fork on port 5005.

```bash
mvn -Dmaven.surefire.debug=true install
```

--------------------------------

### Configure Custom Stack Trace Filter Prefixes (Command Line)

Source: https://maven.apache.org/surefire/maven-surefire-plugin/architecture.html

Configure custom prefixes for stack trace filtering directly from the command line using the 'surefire.stackTraceFilterPrefixes' property. This replaces the default filtering behavior.

```bash
mvn test -Dsurefire.stackTraceFilterPrefixes=org.springframework.,org.junit.
```

--------------------------------

### Configure Security Manager with Surefire

Source: https://maven.apache.org/surefire/maven-surefire-plugin/examples/junit.html

Define a policy file and configure Surefire to use it via the `argLine` parameter. This approach affects tests by changing their security environment.

```xml
<plugins>
  [...] 
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.6.0-M1</version>
        <configuration>
          <argLine>-Djava.security.manager -Djava.security.policy=${basedir}/src/test/resources/java.policy</argLine>
        </configuration>
      </plugin>
  [...] 
</plugins>
```