Documentation

Get Started

VMLens consists of three parts:

The API: Include the com.vmlens.api as a test jar, so that you can use the class AllInterleavings inside your tests.
The Java agent: Add the VMLens agent.jar as vm parameter during your test run or run your tests using the VMLens Maven plugin.
The report builder: Run the builder after your test run. This is done automatically by the VMLens Maven plugin.

Install VMLens

Maven

To use VMLens with Maven, configure a plugin tag to tell Maven that the VMLens plugin should be executed at the test phase. And include com.vmlens.api as test dependency.

<project>
<!-- to include the class AllInterleavings into the test class path.  -->	
<dependency>
  <groupId>com.vmlens</groupId>
  <artifactId>api</artifactId>
  <version>1.2.13</version>
  <scope>test</scope>
</dependency>	
	
<build>
  <plugins>
<!-- to run the vmlens Maven plugin during the Maven test phase  -->	 
    <plugin>
        <groupId>com.vmlens</groupId>
        <artifactId>vmlens-maven-plugin</artifactId>
		<version>1.2.13</version>
        <executions>
            <execution>
                <id>test</id>
                <goals>
                    <goal>test</goal>
                </goals>
            </execution>
        </executions>
	</plugin>
     ...
    </plugins>
</build>
      ...
</project>

See pom.xml for an example.

Gradle

To use VMLens with Gradle add the java agent as vm parameter for the test and process the events after the test run to create the VMLens Report:

import com.vmlens.gradle.VMLens
plugins {
  ...
}
repositories {
    mavenCentral()
}
dependencies {
    testImplementation("com.vmlens:api:1.2.13")
    ...
}
buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("com.vmlens:standalone:1.2.13")
    }
}
tasks.register("vmlensReport") {
    doLast {
        VMLens().process(layout.buildDirectory.getAsFile().get());
    }
}
tasks.test {
    doFirst{
        jvmArgs(VMLens().setup(layout.buildDirectory.getAsFile().get()))
    }
    // VMLens currently does not work with jacoco
    jvmArgumentProviders.removeIf { it::class.java.simpleName == "JacocoAgent" }
    useJUnitPlatform()
    finalizedBy("vmlensReport")
}

See build.gradle.kts for an example.

Standalone

To use VMLens as standalone tool:

Include com.vmlens.api from the Maven Repository as a test jar in your project.
Download the jar standalone-1.2.13.jar from the Maven Repository
Run java -jar standalone-1.2.13.jar install. This creates the agent directory and prints the vm parameter to System.out
Add this vm parameter when you run your test
Run java -jar standalone-1.2.13.jar report. This checks for data races and creates the report

Use VMLens inside your tests

Surround your test with a while loop iterating over all thread interleavings:

import com.vmlens.api.AllInterleavings;
public class TestNonVolatileField {

    @Test
    public void testUpdate() throws InterruptedException {
        try(AllInterleavings allInterleaving = new AllInterleavings("[Name of your test]")) {
            while (allInterleaving.hasNext()) {
               // place your multi-threaded test here
            }
        }
    }
}

Tutorial