Tutorial

Documentation

Tutorial

In this tutorial you will learn how to:

Install VMLens
Write a test
Run the test
Interpret the VMLens report

Install vmlens

The git project vmlens-examples contains the tutorial. Clone this repository:

git clone https://github.com/vmlens/vmlens-examples

VMLens executes the test using a maven plugin. You can see the configuration of this plugin in the pom.xml

<project>
<!-- to include the class AllInterleaving into the test class path.  -->	
<dependency>
  <groupId>com.vmlens</groupId>
  <artifactId>api</artifactId>
  <version>1.2.2</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.2</version>
        <executions>
            <execution>
                <id>test</id>
                <goals>
                    <goal>test</goal>
                </goals>
            </execution>
        </executions>
	</plugin>
     ...
    </plugins>
</build>
      ...
</project>

Write a test

Now we can write our first test. In the example project it is in the class TestIncrement

import com.vmlens.api.AllInterleavings;
public class TestIncrement {
    private int j = 0;
    @Test
    public void testIncrement() throws InterruptedException {
        try(AllInterleavings allInterleavings = new AllInterleavings("tutorial")) {
            while (allInterleavings.hasNext()) {
                j = 0;
                Thread first = new Thread() {
                    @Override
                    public void run() {
                        j++;
                    }
                };
                first.start();
                j++;
                first.join();
                assertThat(j,is(2));
            }
        }
    }

}

You write a normal Junit or TestNG test. In this test you create a new AllInterleavings in a try-with-resources. And iterate over all interleavins using a while loop. Inside the while loop, you place your multithreaded test.

Run the test

Run the test using

mvn install

Interpret the vmlens report

The run will fail with the following build error:

[ERROR] Failed to execute goal com.vmlens:vmlens-maven-plugin:1.2.1:test (test) on project vmlens-examples: There are 1 data races, see C:\workspace\vmlens-examples\target\vmlens-report for the report. -> [Help 1]

Opening index.html in target\vmlens-report will show you the following report:

Clicking on tutorial will show you the trace containing the data race:

Documentation