View Source

Gradle plugin for running groups of tests with varied runtime requirements.

Features

Easily define and run categories of tests
Uses the standard gradle test task
IDE support for running tests in parallel
Built-in allocation testing support for realtime safety
Built on JUnit 5, Gradle, and JVM
Load resources using file APIs with the resource.dir JVM property
runningOnCIServer boolean JVM property to improve running tests locally
Support for projects using ihmc-build plugin
Generate empty test results when no tests are present to avoid false negative builds
Provide list of tests and tags to be run in console output i.e. no uncertainty about which tests are run
Set up full lifecycle logging for tests in --info log level i.e. started, passed, failed, skipped

Download

plugins {
   id("us.ihmc.ihmc-build") version "0.15.5"
   id("us.ihmc.ihmc-ci") version "3.4"
}

User Guide

This plugin defines a concept of categories. Categories are communicated via the category Gradle property (i.e. gradle test -Pcategory=fast)and are used to set up a test process to run tests based on tags, parallel execution settings, and JVM arguments.

Built in categories

The default settings can be scaled via the cpuThreads property (i.e. -PcpuThreads=8). The default value is 8.

Category Configuration Summary

fast

classesPerJVM = 0 // no limit
maxJVMs = 2
maxParallelTests = 4

Run untagged tests as fast as possible.

Assume no special runtime requirements.

allocation classesPerJVM = 0
maxJVMs = 2
maxParallelTests = 1
includeTags += "allocation"
jvmArgs += "allocationAgent" Run only 1 test per JVM process so allocations don't overlap.
Uses provided special accessor, allocationAgentJVMArg,
to get -javaagent:[..]java-allocation-instrumenter[..].jar

Custom categories

In your project's build.gradle.kts (Kotlin):

categories.create("scs-slow")
{
   classesPerJVM = 1   // default: 1
   maxJVMs = 2   // default: 2
   maxParallelTests = 1   // default: 4
   excludeTags += "none"   // default: all
   includeTags += "scs-slow"   // default: empty
   jvmProperties += "some.arg" to "value"   // default: empty List
   jvmArguments += "-Dsome.arg=value"   // default: empty List
   minHeapSizeGB = 1   // default: 1
   maxHeapSizeGB = 8   // default: 4
}

or in build.gradle Groovy:

def gui = categories.create("gui")
gui.classesPerJVM = 0
gui.maxJVMs = 1
gui.initialHeapSizeGB = 6
gui.maxHeapSizeGB = 8

def video = categories.create("video")
video.classesPerJVM = 0  // forkEvery
video.maxJVMs = 1        // maxParallelForks
video.initialHeapSizeGB = 6
video.maxHeapSizeGB = 8

def scsAllocation = categories.create("scs-allocation")
scsAllocation.classesPerJVM = 0  // forkEvery
scsAllocation.maxJVMs = 1        // maxParallelForks
scsAllocation.jvmArguments.add("allocationAgent")
scsAllocation.initialHeapSizeGB = 6
scsAllocation.maxHeapSizeGB = 8

Special JVM argument accessors:

"allocationAgent" - Find location of -javaagent:[..]java-allocation-instrumenter[..].jar

The plugin will do a few other things too:

If -PrunningOnCIServer=true, set -DrunningOnCIServer=true.
Pass -Dresources.dir that points to your resources folder on disk.
Pass -ea JVM argument to enable JVM assertions

Examples

$ gradle test -Pcategory=fast   // run fast tests

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;

@Test
public void fastTest() { ... }   // runs in fast category

@Tag("allocation")
@Test
public void allocationTest() { ... }   // runs in allocation category