Documentation

Get Started

VMLens consists of three parts:

1. The API: Include the com.vmlens.api as a test jar, so that you can use the class AllInterleavings inside your tests.
2. The Java agent: Add the VMLens agent.jar as vm parameter during your test run or run your tests using the VMLens Maven plugin.
3. 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.5</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.5</version>
        <executions>
            <execution>
                <id>test</id>
                <goals>
                    <goal>test</goal>
                </goals>
            </execution>
        </executions>
	</plugin>
     ...
    </plugins>
</build>
      ...
</project>

Standalone

To use VMLens as standalone tool:

1. Include com.vmlens.api from the Maven Repository as a test jar in your project.
2. Download the jar standalone-1.2.5.jar from the Maven Repository
3. Run java -jar standalone-1.2.5.jar install. This creates the agent directory and prints the vm parameter to System.out
4. Add this vm parameter when you run your test
5. Run java -jar standalone-1.2.5.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
            }
        }
    }
}