JUnitPerf

https://noconnor.github.io/JUnitPerf
Admin
JUnitPerf is an API performance testing framework built with JUnit 4 and JUnit 5 for performance...
Tokens:9,728
Snippets:71
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Console Reporter Example Output

Source: https://noconnor.github.io/JUnitPerf

Example output from the console reporter showing performance metrics such as invocations, throughput, and latency. The output includes a PASSED/FAILED status for throughput requirements.

```text
15:55:06.575 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Started at:   2017-10-28 15:55:05
15:55:06.580 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Invocations:  765
15:55:06.580 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator -   - Success:  765
15:55:06.580 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator -   - Errors:   0
15:55:06.580 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator -   - Errors:   0.0% - PASSED
15:55:06.581 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - 
15:55:06.581 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Thread Count: 1
15:55:06.581 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Warm up:      0ms
15:55:06.581 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - 
15:55:06.581 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Execution time: 1000ms
15:55:06.581 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Throughput:     766/s (Required: 10000/s) - FAILED!!
15:55:06.581 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Min. latency:   1.012392ms
15:55:06.582 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Max latency:    3.74209ms
15:55:06.582 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - Ave latency:    1.2975845ms
15:55:06.583 [main] INFO  c.g.n.j.r.p.ConsoleReportGenerator - 

```

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

### Convert unit test to performance test with @JUnitPerfTest

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Annotates a test method with @JUnitPerfTest to run it as a performance test. The example runs for 125 seconds with 50 threads, ramping up to 11K executions per second over 2 seconds, with a 10-second warm-up period.

```java
@Test
@JUnitPerfTest(threads = 50, durationMs = 125_000, rampUpPeriodMs = 2_000, warmUpMs = 10_000, maxExecutionsPerSecond = 11_000)
public void whenExecuting11Kqps_thenApiShouldNotCrash(){
  ... EXECUTE TIME SENSITIVE TASK ...
}

```

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

### CSV Reporter Output Format

Source: https://noconnor.github.io/JUnitPerf

Example CSV output from the CSV reporter. The header includes testName, duration, threadCount, throughput, minLatencyMs, maxLatencyMs, meanLatencyMs, and percentileData. The percentileData field is formatted as percentile1:latency;percentile2:latency; ...

```text
testName,duration,threadCount,throughput,minLatencyMs,maxLatencyMs,meanLatencyMs,percentileData
unittest1,10000,50,101,500000.0,1.430,6.430,1:0.0;2:0.0;3:0.0;4:0.0;5:0.0; ... ;98:4.03434;99:4.83434680

```

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

### Add junit-platform-suite-engine dependency

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Include this dependency in your project to enable suite-level execution.

```xml
<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-suite-engine</artifactId>
    <version>LATEST_VERSION</version>
    <scope>test</scope>
</dependency>
```

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

### JUnitPerf test suite with @Suite and @SelectClasses

Source: https://noconnor.github.io/JUnitPerf/junit5-examples/src/test/java/com/github/noconnor/junitperf/examples/ExampleTestSuiteUsage.java

Defines a JUnit 5 suite that runs TestClassOne and TestClassTwo with JUnitPerf performance testing. Requires the JUnit Jupiter extensions autodetection property to be enabled via @ConfigurationParameter. The suite is executed with Maven using -Dtest=ExampleTestSuiteUsage -DskipTests=false test.

```java
package com.github.noconnor.junitperf.examples;

import com.github.noconnor.junitperf.JUnitPerfReportingConfig;
import com.github.noconnor.junitperf.JUnitPerfTest;
import com.github.noconnor.junitperf.JUnitPerfTestActiveConfig;
import com.github.noconnor.junitperf.JUnitPerfTestRequirement;
import com.github.noconnor.junitperf.examples.existing.TestClassOne;
import com.github.noconnor.junitperf.examples.existing.TestClassTwo;
import org.junit.platform.suite.api.ConfigurationParameter;
import org.junit.platform.suite.api.SelectClasses;
import org.junit.platform.suite.api.Suite;

import static com.github.noconnor.junitperf.examples.utils.ReportingUtils.newHtmlReporter;


//
// To run suite: mvn -Dtest=ExampleTestSuiteUsage -DskipTests=false test
//

@Suite
//@SelectPackages({
//        "com.github.noconnor.junitperf.examples.existing"
//})
@SelectClasses({
        TestClassOne.class,
        TestClassTwo.class
})
// ConfigurationParameter: Required to enable Test Suite Interceptor Reference: https://www.baeldung.com/junit-5-extensions#1-automatic-extension-registration
@ConfigurationParameter(key = "junit.jupiter.extensions.autodetection.enabled", value = "true")
@JUnitPerfTest(totalExecutions = 100)
@JUnitPerfTestRequirement(allowedErrorPercentage = 0.01F)
public class ExampleTestSuiteUsage {

    @JUnitPerfTestActiveConfig
    public static JUnitPerfReportingConfig config = JUnitPerfReportingConfig.builder()
            .reportGenerator(newHtmlReporter("suite_reporter.html"))
            .build();

}

```

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

### Maven Dependency Configuration

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Add the junitperf-junit5 dependency to your project's pom.xml file to use the library.

```xml
<dependency>
  <groupId>com.github.noconnor</groupId>
  <artifactId>junitperf-junit5</artifactId>
  <version>VERSION</version>
</dependency>
```

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

### Configure CsvReportGenerator

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Changes the default HTML reporter to the CSV reporter.

```java
@Rule
public JUnitPerfRule perfTestRule = new JUnitPerfRule(new CsvReportGenerator());
```

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

### Configure Multiple Reporters

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Enables multiple reporters simultaneously by passing them to the JUnitPerfRule constructor.

```java
@Rule
public JUnitPerfRule perfTestRule = new JUnitPerfRule(new CsvReportGenerator(), new HtmlReportGenerator());
```

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

### JUnitPerfTest Annotation Configuration

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Use the @JUnitPerfTest annotation to define performance parameters such as thread count, duration, ramp-up period, warm-up period, and execution rate limits.

```java
@Test
@JUnitPerfTest(threads = 50, durationMs = 125_000, rampUpPeriodMs = 2_000, warmUpMs = 10_000, maxExecutionsPerSecond = 11_000)
public void whenExecuting11Kqps_thenApiShouldNotCrash(){
  ... EXECUTE TIME SENSITIVE TASK ...
}
```

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

### Configure Custom CSV Report Path

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Pass a custom file path string to the CsvReportGenerator constructor to override the default output location.

```java
@JUnitPerfTestActiveConfig
private final static JUnitPerfReportingConfig PERF_CONFIG = JUnitPerfReportingConfig.builder()
        .reportGenerator(new CsvReportGenerator("/some/custom/path/report.csv"))
        .build();
```

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

### Configure JUnitPerfTest for Async Tasks

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Use the @JUnitPerfTest annotation and TestContextSupplier to measure asynchronous task performance. The TestContext is used to signal success or failure to the framework.

```java
@Test
@JUnitPerfTest(durationMs = 125_000, rampUpPeriodMs = 2_000, warmUpMs = 10_000, maxExecutionsPerSecond = 1000)
public void whenExecuting1Kqps_thenApiShouldNotCrash(TestContextSupplier contextSupplier){
   TestContext context = supplier.startMeasurement();
   threadPool.submit( () -> {
      ... EXECUTE ASYNC TASK ...
      ... THEN NOTIFY FRAMEWORK OF SUCCESS/FAILURE...
      context.success();
      // OR
      context.Fail();
  }
}
```

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

### JUnitPerfTestRequirement Annotation Configuration

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Apply the @JUnitPerfTestRequirement annotation to enforce performance thresholds, including throughput, error percentage, and latency percentiles.

```java
@Test
@JUnitPerfTest(threads = 50, durationMs = 125_000, warmUpMs = 10_000, maxExecutionsPerSecond = 11_000)
@JUnitPerfTestRequirement(percentiles = "90:7,95:7,98:7,99:8", executionsPerSec = 10_000, allowedErrorPercentage = 0.10)
public void whenExecuting11Kqps_thenApiShouldNotCrash(){
  ... EXECUTE TIME SENSITIVE TASK ...
}
```

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

### Configure HTML Report Generation

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Use HtmlReportGenerator to specify a custom path for HTML report output. The configuration must be a static field to ensure consistency across test instances.

```java
@JUnitPerfTestActiveConfig
private final static JUnitPerfReportingConfig PERF_CONFIG = JUnitPerfReportingConfig.builder()
        .reportGenerator(new HtmlReportGenerator(getProperty("user.dir") + "/build/reports/" + fileName))
        .build();
```

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

### Configure ConsoleReportGenerator

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Changes the default HTML reporter to the console reporter by passing a ConsoleReportGenerator instance to the JUnitPerfRule constructor.

```java
@Rule
public JUnitPerfRule perfTestRule = new JUnitPerfRule(new ConsoleReportGenerator());
```

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

### Configure Multiple Reporters

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Chain multiple reportGenerator calls to generate different report formats simultaneously, such as both HTML and CSV.

```java
@JUnitPerfTestActiveConfig
private final static JUnitPerfReportingConfig PERF_CONFIG = JUnitPerfReportingConfig.builder()
        .reportGenerator(new CsvReportGenerator())
        .reportGenerator(new HtmlReportGenerator())
        .build();
```

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

### Configure CSV Report Generation

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Use CsvReportGenerator to generate CSV reports. By default, files are saved to ${BUILD_DIR}/reports/junitperf_report.csv.

```java
@JUnitPerfTestActiveConfig
private final static JUnitPerfReportingConfig PERF_CONFIG = JUnitPerfReportingConfig.builder()
        .reportGenerator(new CsvReportGenerator())
        .build();
```

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

### Apply JUnitPerfTestRequirement

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Optionally add the @JUnitPerfTestRequirement annotation to enforce performance thresholds such as latency, throughput, and error rates.

```java
@Test
@JUnitPerfTest(durationMs = 125_000, warmUpMs = 10_000, maxExecutionsPerSecond = 1000)
@JUnitPerfTestRequirement(percentiles = "90:7,95:7,98:7,99:8", executionsPerSec = 1000, allowedErrorPercentage = 0.10)
public void whenExecuting1Kqps_thenApiShouldNotCrash(TestContextSupplier contextSupplier){
   // Starts the task timer
   TestContext context = supplier.startMeasurement();
   threadPool.submit( () -> {
      ... EXECUTE ASYNC TASK ...
      ... THEN NOTIFY FRAMEWORK OF SUCCESS/FAILURE...
      // Stops the task timer and marks task as a success or failure
      context.success();
      // OR
      context.Fail();
  }
}
```

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

### JUnitPerfInterceptor Registration

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Register the JUnitPerfInterceptor using the @ExtendWith annotation on your test class to enable performance testing features.

```java
@ExtendWith(JUnitPerfInterceptor.class)
public class SomeTestClass {

  @Test
  ...
  
  @Test
  ...

} 
```

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

### Configure HTML ReportGenerator

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Configures the JUnitPerfRule to use a custom path for the HTML performance report.

```java
@Rule
public JUnitPerfRule perfTestRule = new JUnitPerfRule(new HtmlReportGenerator("/some/custom/path/report.html"));
```

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

### Implement Custom Report Generator

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Pass a custom implementation of the ReportGenerator interface to the JUnitPerfReportingConfig builder for advanced reporting needs.

```java
@JUnitPerfTestActiveConfig
private final static JUnitPerfReportingConfig PERF_CONFIG = JUnitPerfReportingConfig.builder()
        .reportGenerator(new CustomReportGeneratorImpl())
        .build();
```

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

### Add JUnitPerf Maven dependency

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Declares the JUnitPerf dependency in a Maven pom.xml. Replace VERSION with the desired version. Available from Maven Central.

```xml
<dependency>
  <groupId>com.github.noconnor</groupId>
  <artifactId>junitperf</artifactId>
  <version>VERSION</version>
</dependency>

```

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

### Configure Custom ReportGenerator Implementation

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Passes a custom implementation of the ReportGenerator interface to the JUnitPerfRule constructor.

```java
@Rule
public JUnitPerfRule perfTestRule = new JUnitPerfRule(new CustomReportGeneratorImpl());
```

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

### Aggregate Reports Across Test Classes

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Share a single ReportGenerator instance across multiple test classes to aggregate performance results into one file.

```java
public class ReportingUtils {
    public static final HtmlReportGenerator htmlReporter = new HtmlReportGenerator("src/test/resources/reports/performance_report.html");
}

public class SomeTestClass {

    @JUnitPerfTestActiveConfig
    private final static JUnitPerfReportingConfig PERF_CONFIG = JUnitPerfReportingConfig.builder()
            .reportGenerator(ReportingUtils.htmlReporter)
            .build();
   
    // ... some test code ...
}

public class SomeOtherTestClass {

    @JUnitPerfTestActiveConfig
    private final static JUnitPerfReportingConfig PERF_CONFIG = JUnitPerfReportingConfig.builder()
            .reportGenerator(ReportingUtils.htmlReporter)
            .build();
               
    // ... some other test code ...

}
```

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

### Aggregate Reports Across Test Classes

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Shares a single reporter instance across multiple JUnitPerfRule instances to aggregate results into one report.

```java
public class ReportingUtils {
    public static final HtmlReportGenerator htmlReporter = new HtmlReportGenerator("src/test/resources/reports/performance_report.html");
}

public class SomeTestClass {

    @Rule 
    public JUnitPerfRule perfTestRule = new JUnitPerfRule(ReportingUtils.htmlReporter);
   
    // ... some test code ...
}

public class SomeOtherTestClass {

    @Rule 
    public JUnitPerfRule perfTestRule = new JUnitPerfRule(ReportingUtils.htmlReporter);
   
    // ... some other test code ...

}
```

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

### Exclude @Before/@After methods from statistics

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Creates the JUnitPerfRule with a boolean argument to exclude methods annotated with @Before or @After from statistic calculations, including latency measurements.

```java
@Rule
public JUnitPerfRule perfTestRule = new JUnitPerfRule(true);

```

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

### Add performance requirements with @JUnitPerfTestRequirement

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Adds threshold constraints to a performance test. The test fails if throughput is below 10,000 executions/sec, error rate exceeds 10%, or any specified percentile latency (90:7, 95:7, 98:7, 99:8) is exceeded.

```java
@Test
@JUnitPerfTest(threads = 50, durationMs = 125_000, warmUpMs = 10_000, maxExecutionsPerSecond = 11_000)
@JUnitPerfTestRequirement(percentiles = "90:7,95:7,98:7,99:8", executionsPerSec = 10_000, allowedErrorPercentage = 0.10)
public void whenExecuting11Kqps_thenApiShouldNotCrash(){
  ... EXECUTE TIME SENSITIVE TASK ...
}

```

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

### Override Statistics Calculation

Source: https://noconnor.github.io/JUnitPerf/docs/junit5.html

Provide a custom StatisticsCalculator via a supplier to change how performance statistics are calculated. A new instance is generated for each @Test.

```java
@JUnitPerfTestActiveConfig
private final static JUnitPerfReportingConfig PERF_CONFIG = JUnitPerfReportingConfig.builder()
        .statisticsCalculatorSupplier(() -> new CustomStatisticsCalculator())
        .build();
```

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

### Add JUnitPerfAsyncRule to test class

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Add the async JUnitPerf Rule to your test class to enable asynchronous performance testing.

```java
@Rule
public JUnitPerfAsyncRule rule = new JUnitPerfAsyncRule();
```

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

### Override StatisticsCalculator

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Overrides the default statistics calculation by passing a custom implementation of the StatisticsCalculator interface to the JUnitPerfRule constructor.

```java
@Rule
public JUnitPerfRule perfTestRule = new JUnitPerfRule(new CustomStatisticsCalculatorImpl());
```

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

### Add JUnitPerfRule to test class

Source: https://noconnor.github.io/JUnitPerf/docs/junit4.html

Declares the JUnitPerfRule as a public field in a JUnit4 test class. This rule is required to enable JUnitPerf performance testing.

```java
@Rule
public JUnitPerfRule perfTestRule = new JUnitPerfRule();

```
Tokens:
Raw