JVM annotations

🚩 Table of contents

One JVM by test method

Configure your test JVM
    @HeapSize  |  @Xms  | @Xmx  |  @UseGC (Next release)  |  @EnableGcLogging (Next release)  |  @JvmOptions

Verify heap allocation
    @MeasureHeapAllocation  | @ExpectMaxHeapAllocation  |  @ExpectNoHeapAllocation

Verify resident set size (RSS)
    @MeasureRSS (Next release)  |  @ExpectMaxRSS (Next release)

Profile or check your JVM
    @ProfileJvm  | @ExpectNoJvmIssue

Test examples

One JVM by test method

⚠️ If you use one of the JVM annotations, the test method is executed in a dedicated JVM.

Configure your test JVM

@HeapSize

With this annotation, the test is executed in a specific JVM having the given heap size.

🔧 Parameters

Parameter	Type	Meaning
value	long	Heap size value (Xms=Xmx)
unit	AllocationUnit	Allocation unit

🔎 Example

  @HeapSize(value = 20, unit = AllocationUnit.MEGA_BYTE)

💡 Fixing maximum heap size as a threshold test

@Xms

With this annotation, the test is executed in a specific JVM having the given initial and minimum heap size value.

🔧 Parameters

Parameter	Type	Meaning
value	long	Initial and minimum heap size value
unit	AllocationUnit	Allocation unit

🔎 Example

 @Xms(value = 20, unit = AllocationUnit.MEGA_BYTE)

@Xmx

With this annotation, the test is executed in a specific JVM having the given maximum heap size value.

🔧 Parameters

Parameter	Type	Meaning
value	long	Maximum heap size value
unit	AllocationUnit	Allocation unit

🔎 Example

 @Xmx(value = 20, unit = AllocationUnit.MEGA_BYTE)

💡 Fixing maximum heap size as a threshold test

@UseGC

Available in next QuickPerf release

To specify a GC type.

🔧 Parameters

Parameter	Type	Meaning	Default value
value	org.quickperf.jvm.gc.GC	GC type	GC.DEFAULT

The following GC types are available:

• GC.EPSILON_GC: Epsilon GC - Doc 1, Epsilon GC - Doc 2
• GC.ZGC: ZGC - Doc
• GC.SHENANDOAH: Shenandoah - Doc

🔎 Example

@UseGC(GC.EPSILON_GC)

@EnableGcLogging

Available in next QuickPerf release

To enable GC logging.

The path of the GC log file is displayed in the console:

GC log file: C:\Users\JEANBI~1\AppData\Local\Temp\QuickPerf-1127741195724299919\gc.log

This file can be analysed with the help of a GC log analyzer:

• GCViewer, GCViewer Download 1, GCViewer Download 2
• Censum
• GCeasy, the GC log file can be uploaded
• ...

@JvmOptions

With this annotation, the test is executed in a specific JVM having the given JVM options.

A tool developed by Chris Newland can be used to explore the available JVM options.

🔧 Parameters

Parameter	Type	Meaning
value	String	JVM options

Verify heap allocation

The following annotations use ByteWatcher under the hood:

• https://github.com/danielshaya/ByteWatcher
• https://www.javaspecialists.eu/archive/Issue232.html

They measure heap allocation of the test method thread.

You can for example use @MeasureHeapAllocation and @ExpectMaxHeapAllocation to check the heap allocation cost of a large data structure (containing 1 000 000 elements for example) .

@ExpectNoHeapAllocation can be used to verify that the tested code does not allocate on heap.

@MeasureHeapAllocation

You can measure heap allocation with this annotation.

The measured allocation is displayed in the console.

🔎 Example

@RunWith(QuickPerfJUnitRunner.class)
public class ClassWithMethodAnnotatedWithMeasureAllocation {

    @MeasureHeapAllocation
    @JvmOptions("-XX:+UseCompressedOops -XX:+UseCompressedClassPointers")
    // Heap allocation value depends on UseCompressedOops and UseCompressedClassPointers.
    // QuickPerf works with JDK >= 7u40 where UseCompressedOops is enabled by default.
    // UseCompressedClassPointers was introduced in JDK 8 and is enabled by default.
    @Test
    public void array_list_with_size_100_should_allocate_440_bytes() {
        // java.util.ArrayList: 24 bytes
        //            +
        //  Object[]: 16 + 100 x 4 = 416
        //       = 440 bytes
        ArrayList<Object> data = new ArrayList<>(100);
    }

}

In console:

Measured heap allocation: 440.0 bytes

@ExpectMaxHeapAllocation

With this annotation, the test will fail if heap allocation is greater than expected.

🔧 Parameters

Parameter	Type	Meaning
value	long	Allocation value
unit	AllocationUnit	Allocation unit

🔎 Example

   @ExpectMaxHeapAllocation(value = 440, unit = AllocationUnit.BYTE)
   @Test
   public void array_list_with_size_100_should_allocate_440_bytes() {
       ArrayList<Object> data = new ArrayList<>(100);
   }

@ExpectNoHeapAllocation

With this annotation, the test will fail if heap allocation is detected.

Verify resident set size (RSS)

@MeasureRSS

Available in next QuickPerf release

You can measure the Resident Set Size (RSS) with this annotation.

The measured RSS is displayed in the console.

⚠️ Today this annotation only woks on Linux. You can work on this issue to make the RSS annotations work on MacOS.

@ExpectMaxRSS

Available in next QuickPerf release

With this annotation, the test will fail if the Resident Set Size (RSS) is greater than expected.

⚠️ Today this annotation only woks on Linux. You can work on this issue to make the RSS annotations work on MacOS.

🔧 Parameters

Parameter	Type	Meaning
value	long	value
unit	AllocationUnit	RAM unit

Profile or check your JVM

The following annotations use Java Flight Recorder (JFR) under the hood.

JFR profiling works with Oracle JDK >= 1.7u40 and OpenJDK >= 11.

@ProfileJvm

To profile JVM with Java Flight Recorder (JFR).

The JFR file location is shown in the console. You can open it with Java Mission Control.

🔎 Example

[QUICK PERF] JVM was profiled with Java Flight Recorder (JFR).
The recording file is available here: C:\Users\JEANBI~1\AppData\Local\Temp\QuickPerf-46868616\jvm-profiling.jfr
You can open it with Java Mission Control (JMC).

💡 Where to find Java Mission Control (JMC)?

A jmc executable is available in the _bin _folder of some Oracle JDK (10 >= version >= 1.7u40).

The last JMC release can be found here.

@ExpectNoJvmIssue

Today we consider this annotation as experimental.

With this annotation, JVM is profiled with Java Flight Recorder (JFR).

Based on the profiling, some JMC rules are evaluated. For each rule a score is attributed. The maximum score value is 100. The test will fail if one rule has a score greater than this expected (by default 60)

Things like significant primitives to object conversions can be detected:

💡 With this annotation you can also detect that most of the time is spent to do garbage collection in your test.

💡 If you have the following message in the console

Rule: Stackdepth Setting
Severity: WARNING
Score: 97
Message: Some stack traces were truncated in this recording.

then you can increase the stack depth value in this way:

@JvmOptions("-XX:FlightRecorderOptions=stackdepth=128")

🔧 Parameters

Parameter	Type	Meaning	Default value
score	int	Rule score (<=100)	60

Test examples

With JUnit 4

With JUnit 5

With TestNG