JUnit¶
This plugin provides functions that handle JUnit tests. It has been validated with JUnit 4.12 and JUnit 5.3.2 and should work with any recent version of JUnit 4 and 5.
It can be used directly in a workflow, or indirectly via generators (such as those providing access to test case managers).
A working mvn
installation must be available in the targeted execution environments.
Warning
Surefire versions 3.0.0-M4 and 3.0.0-M5 contain a bug (SUREFIRE-1857) resulting in the Surefire report not containing failure messages. Because of this, the generated Allure reports will also not contain the failure messages.
Hence, it is advised to not use these Surefire releases. Any other version at or above 2.19.1 should be fine.
The functions have a junit
category prefix.
JUnit 5¶
JUnit 5 is a very rich test framework and offers a large combination of possible configurations.
This plugin uses mvn test -Dtest={testclass}#{testmethod}
commands to run tests.
If you are using the JUnit 5 platform in a simple way, this command line works.
POM Examples¶
Here is a pom.xml
file to run tests written in JUnit 5:
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>…</groupId>
<artifactId>…</artifactId>
<version>…</version>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-engine</artifactId>
<version>5.8.2</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<version>5.8.2</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.22.2</version>
</plugin>
</plugins>
</build>
</project>
Here is a pom.xml
file to run tests written in JUnit 4 (in a JUnit 5 environment):
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>…</groupId>
<artifactId>…</artifactId>
<version>…</version>
<dependencies>
<dependency>
<groupId>org.junit.vintage</groupId>
<artifactId>junit-vintage-engine</artifactId>
<version>5.8.2</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
If you are using a more complex configuration, for example with junit-platform-surefire-provider
or with junit-platform-runner
, please check that the mvn test -Dtest=testclass#testmethod
command
works.
Supported types of JUnit 5 tests¶
The following test types are supported:
@Test
@RepeatedTest
@ParameterizedTest
@TestFactory
@TestTemplate
The support of @Nested
classes is not available yet.
Functions¶
junit/mvntest@v1¶
Run a JUnit test class or test case.
The POM file is assumed to be in the current directory. If this not the
case, use working-directory
to specify in which directory the function
is to be performed.
You can also use the extra-options
input to pass additional
parameters like custom settings file to the mvn
command.
Inputs¶
The function has the following inputs:
-
test
(required)The test reference.
-
properties
(optional)The additional properties to use (
-D
option, e.g.foo: value1
would be communicated as-Dfoo=value1
to themvn
command). -
extra-options
(optional)Additional parameters to pass to the
mvn
command.
Reports¶
The function generates the following reports:
-
*.xml
Surefire reports (XML). All
*.xml
files found in thetarget/surefire-reports
directory.The Surefire reports have the
application/vnd.opentestfactory.junit-surefire+xml
content type. -
*.txt
Report formatted as text.
All
*.txt
files found in thetarget/surefire-reports
directory.
Examples¶
In this first example, the POM file is in the current directory:
- uses: junit/mvntest@v1
with:
test: class#method
properties:
foo: value1
bar: value2
In this second example, the POM file is in the cloned repository:
- uses: actions/checkout@v2
with:
repository: https://gitlab.com/myaccount/MyProject.git
- uses: junit/mvntest@v1
with:
test: class#method
properties:
foo: value1
bar: value2
working-directory: MyProject
settings.xml
file is specified:
- uses: junit/mvntest@v1
with:
test: class#method
properties:
foo: value1
bar: value2
extra-options: --settings custom/path/settings.xml
junit/execute@v1¶
An execute
function for use by generators.
Test Reference format¶
{project}/{qualifiedClassName}[#{testMethod}]
With:
{project}
(required): name of the project on the source code repository.{qualifiedClassName}
(required): qualified name of the test class.{testMethod}
(optional): name of the method to test in the test class.
Inputs¶
The function has the following inputs:
-
test
(required)The test reference.
Reports¶
The function generates the following reports:
-
TEST-{qualifiedClassName}.xml
A Surefire report (XML).
{qualifiedClassName}
is the fully qualified name of the test class.The Surefire report has the
application/vnd.opentestfactory.junit-surefire+xml
content type. -
{qualifiedClassName}.txt
Report formatted as text.
-
junit-run-log.txt
Maven full console log output in
.txt
format.
Example¶
- uses: junit/execute@v1-
with:
test: path/to/test/root/qualified.testsuite.ClassName#testMethod
The path to test root is a relative path from the step’s working directory. If not specified, this is the job’s working directory, in which case it must include the repository name.
junit/params@v1¶
A params
function for use by generators.
Inputs¶
The function has the following inputs:
-
data
(required)The data to use for the automated test.
-
format
(required)The format to use for the automated test data.
Example¶
- uses: junit/params@v1
with:
data:
global:
key1: value1
key2: value2
test:
key1: value3
key3: value4
format: format
format
must so far be SQUASHTM_FORMAT (tm.squashtest.org/params@v1
).
data
can have two keys:
global
for defining global parameters.test
for defining test parameters.
Using with inception¶
Please refer to “Inception” for more information on what is inception.
Preload the inception environment with at least the tests execution report data.
Example¶
Assuming the following workflow and two existing execution reports report_1.xml
and report_2.xml
:
metadata:
name: junit Inception
resources:
files:
- surefire-report1
- surefire-report2
jobs:
my_specific_test_suite_job:
runs-on: inception
- uses: actions/prepare-inception@v1
with:
TEST-foo.bar.Weather: ${{ resources.files.surefire-report1 }}
- uses: junit/execute@v1
with:
test: OpenWeather/foo.bar.Weather
my_nonspecific_job:
runs-on: inception
- uses: actions/prepare-inception@v1
with:
TEST-foo.bar.Weather.xml: ${{ resources.files.surefire-report2 }}
- uses: junit/execute@v1
with:
test: OpenWeather/foo.bar.Weather#pub
You can use the following command to run it:
opentf-ctl \
run workflow my_workflow.yaml \
-f surefire-report1=report_1.xml \
-f surefire-report2=report_2.xml
opentf-ctl ^
run workflow my_workflow.yaml ^
-f surefire-report1=report_1.xml ^
-f surefire-report2=report_2.xml
opentf-ctl `
run workflow my_workflow.yaml `
-f surefire-report1=report_1.xml `
-f surefire-report2=report_2.xml
Configuration¶
Hooks can be defined for the provided functions. This can be done in workflow definitions or at the orchestrator level so that they apply to all your workflows.
Configuration at the orchestrator level is done by setting the
JUNIT_PROVIDER_HOOKS
environment variable or by adding the hook definitions in the /app/conf/junit.yaml
service configuration file.
Please refer to “Common provider settings” for more information.