https://github.com/reportportal/agent-java-junit5
JUnit5 integration for ReportPortal
https://github.com/reportportal/agent-java-junit5
java junit5 reportportal
Last synced: 3 months ago
JSON representation
JUnit5 integration for ReportPortal
- Host: GitHub
- URL: https://github.com/reportportal/agent-java-junit5
- Owner: reportportal
- License: apache-2.0
- Created: 2018-01-11T09:20:35.000Z (over 8 years ago)
- Default Branch: develop
- Last Pushed: 2026-03-16T16:38:57.000Z (3 months ago)
- Last Synced: 2026-03-17T03:21:10.898Z (3 months ago)
- Topics: java, junit5, reportportal
- Language: Java
- Size: 2.01 MB
- Stars: 26
- Watchers: 17
- Forks: 22
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ReportPortal JUnit 5 Extension
A JUnit 5 reporter that uploads the results to a ReportPortal server.
> **DISCLAIMER**: We use Google Analytics for sending anonymous usage information such as agent's and client's names, and their versions
> after a successful launch start. This information might help us to improve both ReportPortal backend and client sides. It is used by the
> ReportPortal team only and is not supposed for sharing with 3rd parties.
[](https://central.sonatype.com/artifact/com.epam.reportportal/agent-java-junit5)
[](https://github.com/reportportal/agent-java-junit5/actions/workflows/ci.yml)
[](https://codecov.io/gh/reportportal/agent-java-junit5)
[](https://slack.epmrpp.reportportal.io/)
[](http://stackoverflow.com/questions/tagged/reportportal)
[](http://reportportal.io?style=flat)
The latest version: 5.5.7. Please use `Maven Central` link above to get the client.
---
# ReportPortal [JUnit5](https://junit.org/junit5/) Integration
The repository contains [JUnit5 Extension](https://junit.org/junit5/docs/current/user-guide/#extensions) for [ReportPortal](http://reportportal.io/) integration.
## Getting Started
To start using ReportPortal with JUnit 5 create a service location file:
1. Create folders **_/META-INF/services_** in **_resources_**
2. Put there a file named **_org.junit.jupiter.api.extension.Extension_**ы
3. Put a default implementation reference as a single row into the file: **_com.epam.reportportal.junit5.ReportPortalExtension_**
Example:
__/META-INF/services/org.junit.jupiter.api.extension.Extension__
```none
com.epam.reportportal.junit5.ReportPortalExtension
```
If you desire to configure test *name*, *description* and *tags*:
Extend *ReportPortalExtension*, override *buildStartStepRq()* or other methods (see javadoc comments) and replace
*com.epam.reportportal.junit5.ReportPortalExtension* with fully qualified custom Extension class name in this file.
### Maven
```xml
com.epam.reportportal
agent-java-junit5
5.5.7
```
#### Automatic Extension Registration (optional)
```xml
maven-surefire-plugin
3.0.0-M5
junit.jupiter.extensions.autodetection.enabled = true
```
### Gradle
```groovy
repositories {
mavenLocal()
mavenCentral()
}
testImplementation 'com.epam.reportportal:agent-java-junit5:5.5.7'
```
#### Automatic Extension Registration (optional)
```groovy
test {
useJUnitPlatform()
systemProperty 'junit.jupiter.extensions.autodetection.enabled', true
}
```
## Disabled tests reporting
By default reporting of @Disabled tests is switched off. To switch it on - add next parameter to an execution goal:
- Maven: -DreportDisabledTests=true
- Gradle: -PreportDisabledTests=true
# Step-by-step integration manual for JUnit5
This manual will walk you through the steps for integration of ReportPortal with JUnit5 based project
First, make sure you have installed ReportPortal, the installation steps could be found [here](http://reportportal.io/docs/Installation-steps)
We’ll assume that ReportPortal is installed and running on
## Step 1 - Create new project (Maven)
> If you want to integrate ReportPortal with existing project, go to step 2
#### 1.1 Start new maven project
#### 1.2 Enter GroupId and ArtifactId
#### 1.3 Enter project name
## Step 2 - Configure pom.xml
#### 2.1 Add following dependencies:
*ReportPortal agent implementation for JUnit 5*
```xml
com.epam.reportportal
agent-java-junit5
5.5.7
```
> Latest version of the agent, could be found [here](https://search.maven.org/search?q=g:%22com.epam.reportportal%22%20AND%20a:%22agent-java-junit5%22)
The ReportPortal agent for JUnit 5 includes the JUnit 5 library dependency, and so we won't need other explicit JUnit 5 dependencies
However, if you are adding ReportPortal agent to existing project, with JUnit 5 dependency already declared, pay attention to dependency transitivity and the conflicts that might arise
> More about JUnit 5 dependencies structure could be found [here](https://junit.org/junit5/docs/current/user-guide/#dependency-metadata)
#### 2.2 Add ReportPortal dedicated logger wrapper
ReportPortal provides its own logger implementations for major logging frameworks like *log4j* and *logback*
If you prefer using **Logback** logging library, add following dependencies:
*ReportPortal logback logger dependency*
```xml
com.epam.reportportal
logger-java-logback
5.2.2
```
> Up to date version could be found [here](https://search.maven.org/search?q=g:%22com.epam.reportportal%22%20AND%20a:%22logger-java-logback%22)
*The logback itself*
```xml
ch.qos.logback
logback-classic
1.2.10
```
If you prefer using **Log4j** logging library, add following dependencies:
*ReportPortal log4j logger dependency*
```xml
com.epam.reportportal
logger-java-log4j
5.2.2
```
> Up to date version could be found [here](https://search.maven.org/search?q=g:%22com.epam.reportportal%22%20AND%20a:%22logger-java-log4j%22)
*The log4j itself*
```xml
org.apache.logging.log4j
log4j-api
2.17.1
org.apache.logging.log4j
log4j-core
2.17.1
```
## Step 3 - Add the test with logging
#### 3.1 Add simple test method
Create a test class `MyTests` in the test directory and add JUnit 5 test method there
```java
package com.mycompany.tests;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
import org.junit.jupiter.api.*;
public class MyTests {
private static final Logger LOGGER = LogManager.getLogger(MyTests.class);
@Test
void testMySimpleTest() {
LOGGER.info("Hello from my simple test");
}
}
```
#### 3.2 Add `log4j2.xml` file to `resources` folder
*Example:*
```xml
```
It's needed to add `ReportPortalAppender` into this (as shown in the example)
By this moment, your project tree should look somewhat like the this:
## Step 4 - Configuring ReportPortal
#### 4.1 Open ReportPortal UI
Go to *http:$IP_ADDRESS_OF_REPORT_PORTAL:8080* (by default it is *http://localhost:8080*)
Login as **Admin** user and create the project (more details [here](https://reportportal.io/docs/category/installation-steps) and [here](https://reportportal.io/docs/reportportal-configuration/CreationOfProjectAndAddingUsers/#create-a-project))
#### 4.2 Add users to your project:
Go to *Administrative* -> *My Test Project* -> *Members* -> *Add user*
> Example link *http://localhost:8080/ui/#administrate/project-details/my_test_project/members*
## Step 5 - Link ReportPortal with your tests
#### 5.1 - Add `reportportal.properties`
After you have created new user in your project, you can get `reportportal.properties` file example from the user *Profile* page
To do that, login as created user and go to *User icon* in header -> *Profile*
There, in *Configuration Examples* section, you can find the example of `reportportal.properties` file for that user
Returning back to the code. In your project, create file named `reportportal.properties` in `resources` folder and copy&paste the contents form the user profile page
*Example:*
```properties
[reportportal.properties]
rp.endpoint = http://localhost:8080
rp.uuid = d50810f1-ace9-44fc-b1ba-a0077fb3cc44
rp.launch = jack_TEST_EXAMPLE
rp.project = my_test_project
rp.enable = true
```
> More details on `reportportal.properties` file could be found [here](https://github.com/reportportal/client-java)
#### 5.2 - Register ReportPortal agent in JUnit 5
There are two options how you can enable ReportPortal extension in your tests:
- By specifying `@ExtendWith` annotation
- By service location
##### Register ReportPortal extension with annotation
Each test marked with `@ExtendWith(ReportPortalExtension.class)` will be reporter to ReportPortal.
This is an inheritable annotation, that means you can put it on a superclass and all child classes will
also use a specified extension.
For example:
```java
import com.epam.reportportal.junit5.ReportPortalExtension;
import org.junit.jupiter.api.extension.ExtendWith;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.EnumSource;
@ExtendWith(ReportPortalExtension.class)
public class EnumParametersTest {
public enum TestParams {
ONE,
TWO
}
@ParameterizedTest
@EnumSource(TestParams.class)
public void testParameters(TestParams param) {
System.out.println("Test: " + param.name());
}
}
```
##### Register ReportPortal extension through service location
For those who implement their own custom extensions we decided to remove `/META-INF/services` file from our project.
To use our standard non-custom extension you need to add this file into your project by yourself.
To do that create a file named `org.junit.jupiter.api.extension.Extension` in `src/test/resources/META-INF/services` folder
with the following content:
```text
com.epam.reportportal.junit5.ReportPortalExtension
```
As a final step you need to tell JUnit to register our ReportPortal agent, and there are multiple ways for doing that:
* method 1 - via Maven Surefire/Failsafe plugin (maven only)
* method 2 - via JVM system property
* method 3 - via `junit-platform.properties` file
* method 4 - via Gradle (gradle only)
###### Method 1 - using Maven Surefire/Failsafe plugin (maven only)
Add a `build` section and Maven Surefire plugin with the following configuration section to `pom.xml`
```xml
maven-surefire-plugin
3.0.0-M5
junit.jupiter.extensions.autodetection.enabled = true
```
The `junit.jupiter.extensions.autodetection.enabled = true` configuration parameter of the Surefire plugin links ReportPortal agent with the tests
*Full pom.xml file example*
```xml
[pom.xml]
4.0.0
com.mycompany
MyProject
1.0-SNAPSHOT
com.epam.reportportal
agent-java-junit5
5.5.7
com.epam.reportportal
logger-java-log4j
5.2.2
org.apache.logging.log4j
log4j-api
2.17.1
org.apache.logging.log4j
log4j-core
2.17.1
maven-surefire-plugin
3.0.0-M5
junit.jupiter.extensions.autodetection.enabled = true
```
Now the ReportPortal agent is linked to your tests and when you run the tests with maven, the results should be sent to ReportPortal
> *Important note*. With this approach, only the tests executed via maven will be sent to ReportPortal, while tests ran by IDE will not trigger the ReportPortal agent and therefore the test-report won't be generated
To have test results to be sent to ReportPortal when executed from IDE (without maven), follow the steps below
###### Method 2 - using JVM system property
Another way to link test runs with ReportPortal is to add JVM system property to the run arguments for test runs
Here is the example of adding run arguments with IntelliJ IDEA
In Intellij IDEA go to *Run* -> *Edit Configurations* -> click on "+" sign -> select JUnit
Enter the name of the run, select classes and/or methods to be executed in this configuration and add the following line into *VM Options* field:
```shell
-Djunit.jupiter.extensions.autodetection.enabled=true
```
When you are done adding local run configuration, simply go to *Run* -> *Run * and that test run results should be sent to ReportPortal
###### Method 3 - using `junit-platform.properties` file
There is another option of linking ReportPortal with your JUnit 5 tests
Add `junit-platform.properties` file to your `resources` folder and add the following line there:
```shell
junit.jupiter.extensions.autodetection.enabled=true
```
> More details about JUnit 5 extensions detection configuration could be found [here](https://junit.org/junit5/docs/current/user-guide/#extensions-registration-automatic)
With this approach, the test report will be generated and sent to ReportPortal in any type of test run, whether it was via maven, gradle or via IDE
###### Method 4 - using Gradle test task (Gradle only)
Starting from gradle version `4.6` it provides native support for JUnit 5 tests via `useJUnitPlatform()`, more details [here](https://junit.org/junit5/docs/current/user-guide/#running-tests-build)
Assuming that you have the gradle project setup, add/edit your `test` task in `gradle.build` file with the following code:
```gradle
test {
testLogging.showStandardStreams = true
useJUnitPlatform()
systemProperty 'junit.jupiter.extensions.autodetection.enabled', true
}
```
> Please note, that using this method, the test report will be generated only if you ran your tests with Gradle (e.g. `gradle clean test`)
*Full `build.gradle` file example:*
```groovy
[build.gradle]
apply plugin: 'java'
sourceCompatibility = 1.8
targetCompatibility = 1.8
repositories {
mavenLocal()
mavenCentral()
}
dependencies {
implementation 'com.epam.reportportal:logger-java-log4j:5.2.2'
implementation 'org.apache.logging.log4j:log4j-api:2.17.1'
implementation 'org.apache.logging.log4j:log4j-core:2.17.1'
implementation 'com.epam.reportportal:agent-java-junit5:5.5.7'
}
test {
testLogging.showStandardStreams = true
useJUnitPlatform()
systemProperty 'junit.jupiter.extensions.autodetection.enabled', true
}
```
## Step 6 - Observing test run report
After you linked the ReportPortal JUnit 5 agent using one of the approaches described above and ran your tests, you should be able to see the results in your ReportPortal UI instance
To do that, login to ReportPortal, and go to *Left Panel* -> *Launches*
You should see the launch there, with the name equal to the value of `rp.launch` from your `reportportal.properties` file
*Example:*
You can also see the test classes and individual test results by clicking on the launch name and going deeper
# Copyright Notice
Licensed under the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license (see the LICENSE.md file).