IHMC CI Documentation

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.

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