https://github.com/vmlens/vmlens
Deterministic Unit Tests for Multithreaded Java
https://github.com/vmlens/vmlens
asynchronous concurrency concurrent concurrent-programming java multithreading testing
Last synced: 12 days ago
JSON representation
Deterministic Unit Tests for Multithreaded Java
- Host: GitHub
- URL: https://github.com/vmlens/vmlens
- Owner: vmlens
- License: apache-2.0
- Created: 2020-07-21T11:46:23.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2026-01-02T15:41:49.000Z (23 days ago)
- Last Synced: 2026-01-08T23:18:51.704Z (17 days ago)
- Topics: asynchronous, concurrency, concurrent, concurrent-programming, java, multithreading, testing
- Language: Java
- Homepage: https://vmlens.com
- Size: 9.81 MB
- Stars: 137
- Watchers: 5
- Forks: 12
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-java - Vmlens
README
# Deterministic Unit Tests for Multithreaded Java
# Example
The following example shows how to test multithreaded, concurrent Java with vmlens:
```Java
import com.vmlens.api.AllInterleavings;
public class TestNonVolatileField {
private int j = 0;
@Test
public void testUpdate() throws InterruptedException {
try(AllInterleavings allInterleavings = new AllInterleavings("testNonVolatileField")) {
while (allInterleavings.hasNext()) {
Thread first = new Thread() {
@Override
public void run() {
j++;
}
};
first.start();
j++;
first.join();
}
}
}
}
```
VMLens detects the data race and generates the following report:
See [test-vmlens-maven-plugin](https://github.com/vmlens/vmlens/tree/master/test-vmlens-maven-plugin/src/test/java/com/vmlens/test/maven/plugin) for more examples.
# Installation
## 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 the jar com.vmlens.api as test dependency.
```XML
com.vmlens
api
1.2.24
test
com.vmlens
vmlens-maven-plugin
1.2.24
test
test
...
...
```
See [pom.xml](https://github.com/vmlens/vmlens/blob/master/test-vmlens-maven-plugin/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:
```Java
import com.vmlens.gradle.VMLens
plugins {
...
}
repositories {
mavenCentral()
}
dependencies {
testImplementation("com.vmlens:api:1.2.24")
...
}
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath("com.vmlens:standalone:1.2.24")
}
}
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](https://github.com/vmlens/vmlens-examples/blob/master/build.gradle.kts) for an example.
## Standalone
To use VMLens as a standalone tool:
1. Include com.vmlens.api from the [Maven Repository](https://repo1.maven.org/maven2/com/vmlens/api/1.2.24/) as a test jar in your project.
1. Download the jar standalone-1.2.24.jar from the [Maven Repository](https://repo1.maven.org/maven2/com/vmlens/standalone/1.2.24/)
1. Run java -jar standalone-1.2.24.jar install. This creates the agent directory and prints the vm parameter to System.out
1. Add this vm parameter when you run your test
2. Run java -jar standalone-1.2.24.jar report. This checks for data races and creates the report
# Supported Java Versions
VMLens runs with JDK 9 to 25
# Documentation
Read the documentation [here](https://vmlens.com/docs/).
# Questions? Problems? Suggestions?
Contact me at [thomas.krieger@vmlens.com](mailto:thomas.krieger@vmlens.com)
# License
[Apache License 2.0](https://github.com/vmlens/vmlens/blob/master/LICENSE)