IHMC CI

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

Download

plugins {
   id("us.ihmc.ihmc-build") version "0.15.1"
   id("us.ihmc.ihmc-ci") version "1.2.0"
}

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 += getAllocationAgentJVMArg()`	Run only 1 test per JVM process so allocations don't overlap. Uses provided special accessor, `allocationAgentJVMArg`, to get `-javaagent:[..]java-allocation-instrumenter[..].jar`
`scs`	`classesPerJVM = 1` `maxJVMs = 2` `maxParallelTests = 1` `includeTags += "scs"` `jvmProperties.putAll(getScsDefaultJVMProps())` `minHeapSizeGB = 6` `maxHeapSizeGB = 8`	Run SCS tests. (Will eventually move SCS Gradle plugin) These are the default settings for SCS. Accessible via `getSCSDefaultJVMArgs()`.
`video`	`classesPerJVM = 1` `maxJVMs = 2` `maxParallelTests = 1` `includeTags += "video"` `jvmProperties["create.scs.gui"] = "true"` `jvmProperties["show.scs.windows"] = "true"` `jvmProperties["create.videos.dir"] = "/home/shadylady/bamboo-videos/"` `jvmProperties["show.scs.yographics"] = "true"` `jvmProperties["java.awt.headless"] = "false"` `jvmProperties["create.videos"] = "true"` `jvmProperties["openh264.license"] = "accept"` `jvmProperties["disable.joint.subsystem.publisher"] = "true"` `jvmProperties["scs.dataBuffer.size"] = "8142"` `minHeapSizeGB = 6` `maxHeapSizeGB = 8`	Run SCS video recordings. (Will eventually move SCS Gradle plugin)

Custom categories

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

categories.create("slow-scs")
{
   classesPerJVM = 1   // default: 1
   maxJVMs = 2   // default: 2
   maxParallelTests = 1   // default: 4
   excludeTags += "none"   // default: all
   includeTags += ["slow", "scs"]   // 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

Special JVM argument accessors:

getAllocationAgentJVMArg() - 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