Installation Guide #

To use JMC effectively, two components are necessary - The JMC library as a dependency, and test configuration to enable automatic instrumentation.

JMC Library dependency #

Add the JMC library dependency to the project as a testImplementation dependency.

testImplementation("org.mpi-sws.jmc:jmc:0.1.1")

Alternatively, JMC can be built from source and published in local maven repository if additional customization is needed.

JMC Test configuration #

To run tests using JMC annotate tests with @JmcCheck and @JmcCheckConfiguration annotations. JMC first intercepts and modifies the compiled bytecode before running the tests. The interception is done through a Java Agent and hence needs to be passed as an argument to the JVM.

Integration support
Note that we currently support JUnit5 integration when running tests. Therefore, the annotations are ineffective when using other testing frameworks. We plan to support more frameworks in future.

To configure using the agent simply use the JMC plugin that automatically adds the argument and does the necessary configuration to enable instrumentation.

plugins {
    id("org.mpi-sws.jmc.gradle") version "0.1.1"
}

Manual Instrumentation configuration #

Alternatively, add the following task configuration to manually configure the instrumentation agent.

val agentDependencies by configurations.creating

dependencies {
    agentDependencies("org.mpi-sws.jmc:jmc:0.1.1")
    agentDependencies("org.mpi-sws.jmc:jmc-agent:0.1.1")
}

tasks.test {
    useJUnitPlatform()

    val agentJar = agentDependencies.find { it.name.contains("jmc-agent-0.1.1") }?.absolutePath
    val libraryJar = agentDependencies.find { it.name.contains("jmc-0.1.1") }?.absolutePath

    val agentArg = "-javaagent:$agentJar=debug,instrumentingPackages=<root_package_name>,jmcRuntimeJarPath=$libraryJar"
    jvmArgs(agentArg)
}

The configuration ensures that JVM is passed the additional argument with the Agent JAR (in -javaagent) when running tests. Refer to Agent docs for more details about the agent arguments.