Maven Surefire Plugin

https://maven.apache.org/surefire/maven-surefire-plugin/
Admin
Maven Surefire Plugin is a Maven build plugin used to execute unit tests during the test phase and...
Tokens:31,883
Snippets:243
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Surefire includesFile example

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

Example content for the `includesFile` parameter, showing path, simple, and regex include patterns. Blank lines and lines starting with # are ignored.

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

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

### forkedProcessTimeoutExtensionContext configuration example

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

Example configuration for the forkedProcessTimeoutExtensionContext parameter, showing the jstack.output.location key. The example appears truncated in the source.

```xml
<configuration>
    <forkedProcessTimeoutExtensionContext>
        <jstack.output.location>${project.build.directory/jstacks
    

}
```

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

### Excludes file example

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

Example of an excludes file with path, simple, and regex excludes. Blank lines and lines starting with # are ignored.

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

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

### forkedProcessTimeoutExtensionContext configuration example

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

Example configuration for the forkedProcessTimeoutExtensionContext parameter, showing the jstack.output.location key set to a directory path.

```xml
<configuration>
    <forkedProcessTimeoutExtensionContext>
        <jstack.output.location>${project.build.directory/jstacks
    
}
```

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

### Method filtering in exclusions file

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

Since 3.0.0-M6, method filtering support is provided in the exclusions file. The example shows the format: pkg.SomeTest#testMethod.

```text
pkg.SomeTest#testMethod
```

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

### Surefire -Dtest regex syntax example

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

Complex syntax for the test parameter using regex patterns with %regex[]. Exclusions are prefixed with !, and method patterns are supported.

```text
-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]
```

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

### Surefire -Dtest complex syntax example

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

Complex syntax for the test parameter, supported since Surefire 2.19, allowing multiple patterns in one parameter. Patterns prefixed with ! are excluded, and method selection uses #.

```text
-Dtest=???Test, !Unstable*, pkg/**/Ci*leTest.java, *Test#test*One+testTwo?????, #fast*+slowTest
```

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

### Build and test commands

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

Commands for building and testing the Maven Surefire project. Requires Maven 3.6.3+ and JDK 8+.

```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
```

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

### <systemProperties>

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

List of System properties to pass to a provider. Deprecated; use systemPropertyVariables instead.

```APIDOC
## <systemProperties>

### Description
List of System properties to pass to a provider.

### Deprecation
**Deprecated.** use `systemPropertyVariables` instead

### Parameters
- **Type** : `java.util.Properties`
- **Required** : `No`

### See Also
- `systemPropertyVariables` for how the effective provider properties are calculated
```

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

### Pass non-String Maven variable literally in systemProperties

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

Example showing that non-String Maven variables are passed literally. The expression ${project.build.outputDirectory} is a File type, so it is passed as the literal string.

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

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

### <systemPropertiesFile>

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

Properties file being used as system properties passed to the provider.

```APIDOC
## <systemPropertiesFile>

### Description
Properties file being used as system properties passed to the provider.

### Parameters
- **Type** : `java.io.File`
- **Required** : `No`
- **User Property** : `surefire.systemPropertiesFile`

### See Also
- `systemPropertyVariables` for how the effective provider properties are calculated
```

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

### Consumer plugin configuration with extension dependency

Source: https://maven.apache.org/surefire/maven-surefire-plugin/timeout-extension-guide.html

Declares the extension JAR as a dependency of maven-surefire-plugin (not as a project test dependency) so Surefire discovers it on the plugin classpath. Configures forkedProcessTimeoutInSeconds and the heapdump.output.location context value.

```xml
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <configuration>
    <forkedProcessTimeoutInSeconds>600</forkedProcessTimeoutInSeconds>
    <forkedProcessTimeoutExtensionContext>
      <heapdump.output.location>${project.build.directory}/heap-dumps</heapdump.output.location>
    </forkedProcessTimeoutExtensionContext>
  </configuration>
  <dependencies>
    <dependency>
      <groupId>com.example.surefire</groupId>
      <artifactId>my-timeout-extension</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>
</plugin>

```

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

### HeapDumpTimeoutExtension implementation

Source: https://maven.apache.org/surefire/maven-surefire-plugin/timeout-extension-guide.html

Example implementation of ForkedProcessTimeoutExtension that triggers a heap dump via jcmd when a timeout is detected. Uses the extension context to read the heapdump.output.location key, defaults to the reports directory, and logs a warning if the PID is unknown.

```java
package com.example.surefire;

import java.io.File;
import java.nio.file.Files;
import java.nio.file.Path;

import org.apache.maven.plugin.surefire.log.api.ConsoleLogger;
import org.apache.maven.surefire.api.suite.RunResult;
import org.apache.maven.surefire.extensions.ForkedProcessTimeoutContext;
import org.apache.maven.surefire.extensions.ForkedProcessTimeoutExtension;

public class HeapDumpTimeoutExtension implements ForkedProcessTimeoutExtension {

    private static final String OUTPUT_KEY = "heapdump.output.location";

    @Override
    public void onTimeoutDetected(ForkedProcessTimeoutContext context) throws Exception {
        ConsoleLogger log = context.getConsoleLogger();
        long pid = context.getPid();
        if (pid <= 0L) {
            log.warning("HeapDumpTimeoutExtension: unknown PID, skipping fork " + context.getForkNumber());
            return;
        }
        String dir = context.getExtensionContext().getOrDefault(
                OUTPUT_KEY, context.getReportsDirectory().getAbsolutePath());
        Path out = Path.of(dir, "heap-fork-" + context.getForkNumber() + "-" + pid + ".hprof");
        Files.createDirectories(out.getParent());

        // Spawn jcmd ${pid} GC.heap_dump
        new ProcessBuilder("jcmd", Long.toString(pid), "GC.heap_dump", out.toString())
                .redirectErrorStream(true)
                .inheritIO()
                .start()
                .waitFor();

        log.info("HeapDumpTimeoutExtension: wrote " + out);
    }

    @Override
    public void onForkExited(ForkedProcessTimeoutContext context, RunResult runResult) {
        // optional: upload to S3, post to Slack, etc.
    }
}

```

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

### Enable jstack extension via system property

Source: https://maven.apache.org/surefire/maven-surefire-plugin/timeout-extension-guide.html

Per-build alternative to enable the jstack extension. If both POM and property are set, the property wins because it is processed first.

```bash
mvn verify -Dsurefire.timeout.jstack.enabled=true
```

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

### ServiceLoader registration file

Source: https://maven.apache.org/surefire/maven-surefire-plugin/timeout-extension-guide.html

Content of the file src/main/resources/META-INF/services/org.apache.maven.surefire.extensions.ForkedProcessTimeoutExtension. Contains one fully-qualified class name per line for ServiceLoader registration.

```text
com.example.surefire.HeapDumpTimeoutExtension

```

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

### Browse maven-surefire-plugin repository

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

URL for browsing the source repository of the maven-surefire-plugin at version surefire-3.6.0.

```text
https://github.com/apache/maven-surefire/tree/surefire-3.6.0/maven-surefire-plugin
```

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

### Configure systemPropertyVariables in maven-surefire-plugin

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

Configure the maven-surefire-plugin to pass system properties to the Surefire provider. Use this instead of the deprecated systemProperties parameter. Values can be Maven properties that resolve to String or arbitrary literals.

```xml
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.6.0</version>
        <configuration>
          <systemPropertyVariables>
            <propertyName>propertyValue</propertyName>
            <buildDirectory>${project.build.directory}</buildDirectory>
            [...]
          </systemPropertyVariables>
        </configuration>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
```
Tokens:
Raw