reportportal / agent-java-junit5

JUnit5 integration for ReportPortal

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.

The latest version: 5.3.2. Please use Maven Central link above to get the client.

---

ReportPortal JUnit5 Integration

The repository contains JUnit5 Extension for ReportPortal 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

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

<dependency>
   <groupId>com.epam.reportportal</groupId>
   <artifactId>agent-java-junit5</artifactId>
   <version>5.3.2</version>
</dependency>

Automatic Extension Registration (optional)

<build>
    <plugins>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.0.0-M5</version>
            <configuration>
                <properties>
                    <configurationParameters>
                        junit.jupiter.extensions.autodetection.enabled = true
                    </configurationParameters>
                </properties>
            </configuration>
        </plugin>
    </plugins>
</build>

Gradle

repositories {
    mavenLocal()
    mavenCentral()
}

testImplementation 'com.epam.reportportal:agent-java-junit5:5.3.2'

Automatic Extension Registration (optional)

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

We’ll assume that ReportPortal is installed and running on http://localhost:8080

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

<dependency>
    <groupId>com.epam.reportportal</groupId>
    <artifactId>agent-java-junit5</artifactId>
    <version>5.3.2</version>
</dependency>

Latest version of the agent, could be found here

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

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

<dependency>
    <groupId>com.epam.reportportal</groupId>
    <artifactId>logger-java-logback</artifactId>
    <version>5.2.2</version>
</dependency>

Up to date version could be found here

The logback itself

<dependency>
    <groupId>ch.qos.logback</groupId>
    <artifactId>logback-classic</artifactId>
    <version>1.2.10</version>
</dependency>

If you prefer using Log4j logging library, add following dependencies:

ReportPortal log4j logger dependency

<dependency>
    <groupId>com.epam.reportportal</groupId>
    <artifactId>logger-java-log4j</artifactId>
    <version>5.2.2</version>
</dependency>

Up to date version could be found here

The log4j itself

<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.17.1</version>
</dependency>

<dependency>
     <groupId>org.apache.logging.log4j</groupId>
     <artifactId>log4j-core</artifactId>
     <version>2.17.1</version>
</dependency>

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

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 version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="ConsoleAppender" target="SYSTEM_OUT">
            <PatternLayout
                    pattern="%d [%t] %-5level %logger{36} - %msg%n%throwable"/>
        </Console>
        <ReportPortalLog4j2Appender name="ReportPortalAppender">
            <PatternLayout
                    pattern="%d [%t] %-5level %logger{36} - %msg%n%throwable"/>
        </ReportPortalLog4j2Appender>
    </Appenders>
    <Loggers>
        <Root level="DEBUG">
            <AppenderRef ref="ConsoleAppender"/>
            <AppenderRef ref="ReportPortalAppender"/>
        </Root>
    </Loggers>
</Configuration>

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 and here)

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:

[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

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:

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:

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

<build>
    <plugins>
        <plugin>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.0.0-M5</version>
            <configuration>
                <properties>
                    <configurationParameters>
                        junit.jupiter.extensions.autodetection.enabled = true
                    </configurationParameters>
                </properties>
            </configuration>
        </plugin>
    </plugins>
</build>

The junit.jupiter.extensions.autodetection.enabled = true configuration parameter of the Surefire plugin links ReportPortal agent with the tests

Full pom.xml file example

[pom.xml]
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.mycompany</groupId>
    <artifactId>MyProject</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>com.epam.reportportal</groupId>
            <artifactId>agent-java-junit5</artifactId>
            <version>5.3.2</version>
        </dependency>

        <dependency>
            <groupId>com.epam.reportportal</groupId>
            <artifactId>logger-java-log4j</artifactId>
            <version>5.2.2</version>
        </dependency>

        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-api</artifactId>
            <version>2.17.1</version>
        </dependency>

        <dependency>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j-core</artifactId>
            <version>2.17.1</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.0.0-M5</version>
                <configuration>
                    <properties>
                        <configurationParameters>
                            junit.jupiter.extensions.autodetection.enabled = true
                        </configurationParameters>
                    </properties>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

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:

-Djunit.jupiter.extensions.autodetection.enabled=true

When you are done adding local run configuration, simply go to Run -> Run <test_run_name> 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:

junit.jupiter.extensions.autodetection.enabled=true

More details about JUnit 5 extensions detection configuration could be found here

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

Assuming that you have the gradle project setup, add/edit your test task in gradle.build file with the following code:

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:

[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.3.2'
}

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 license (see the LICENSE.md file).