https://github.com/vmlens/vmlens
unit-testing multi-threaded applications on the JVM made easy
https://github.com/vmlens/vmlens
concurrent java multithreading testing
Last synced: about 2 months ago
JSON representation
unit-testing multi-threaded applications on the JVM made easy
- Host: GitHub
- URL: https://github.com/vmlens/vmlens
- Owner: vmlens
- License: apache-2.0
- Created: 2020-07-21T11:46:23.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-10-08T11:39:30.000Z (over 2 years ago)
- Last Synced: 2023-02-28T22:42:57.714Z (about 2 years ago)
- Topics: concurrent, java, multithreading, testing
- Language: Java
- Homepage: https://vmlens.com
- Size: 5.77 MB
- Stars: 98
- Watchers: 8
- Forks: 7
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-java - Vmlens
README
# vmlens, unit-testing multi-threaded applications on the JVM made easy
# Why vmlens?
Running your tests with multiple threads does not work. Bugs depend on a specific thread interleaving, which is often impossible to reach by simply rerunning your test multiple times. And data races only occur on specific hardware architectures and JVMs.
Therefore vmlens uses the Java Memory Model to execute all possible thread interleavings and to check for data races in the program flow. [This blog post](https://vmlens.com/articles/cp/java_memory_model_enables_tests/) describes how vmlens uses the Java Memory Model to test all thread interleavings.
## Easy to use
Using vmlens is easy.
Surround your test with a while loop iterating over all thread interleavings using the class AllInterleaving.
# Example
The following example shows how to write multi-threaded tests with vmlens:
```Java
import com.vmlens.api.AllInterleavings;
public class TestUpdateWrong {
public void update(ConcurrentHashMap map) {
Integer result = map.get(1);
if (result == null) {
map.put(1, 1);
} else {
map.put(1, result + 1);
}
}
@Test
public void testUpdate() throws InterruptedException {
try (AllInterleavings allInterleavings =
new AllInterleavings("TestUpdateWrong");) {
// surround the test with a while loop, iterationg over
// the class AllInterleavings
while (allInterleavings.hasNext()) {
final ConcurrentHashMap map =
new ConcurrentHashMap();
Thread first = new Thread(() -> {
update(map);
});
Thread second = new Thread(() -> {
update(map);
});
first.start();
second.start();
first.join();
second.join();
assertEquals(2,map.get(1).intValue());
}
}
}
}
```
In your test method, you surround the code you want to test with a while loop iterating
over the class AllInterleavings.
vmlens executes the block inside the while loop multiple times, for each thread interleaving once.
If the test fails vmlens shows the thread interleaving which led to the failure. If the test succeeds vmlens
shows the last thread interleaving.
The above example test fails, and vmlens reports the interleaving which led to the failed assertion:
In maven, you can see this report by clicking on the link TestUpdateWrong in the file target/interleave/elements.html.
In eclipse you can see the report by clicking on the link TestUpdateWrong in the view under Window -> Show View -> Other... -> vmlens -> vmlens Explorer.
The maven reports are [described here](https://vmlens.com/help/manual/#maven-reports). The eclipse views are [described here](https://vmlens.com/help/manual/#the-report).
## How to run the test
You can run the test in eclipse using the vmlens run short cut for JUnit. Right click on the JUnit class -> Run As -> JUnit Test traced with vmlens.
To run the test with maven put the vmlens interleave plugin in your maven pom.xml [as described here](https://vmlens.com/help/manual/#running-tests-maven).
## Next steps
[Read here more](https://vmlens.com/help/manual/#data_races_deadlocks) about how to use vmlens for testing multi-threaded software. And download and run [the example tests.](https://github.com/vmlens/vmlens-examples)
# Download
## Eclipse
Install from marketplace:
- Start Eclipse (version 4.4 or greater)
-
Or install directly from the update site:
- Start Eclipse
- Select Help>Install New Software…
- Work with: https://vmlens.com/download/site/
To use the class AllInterleavings you need to include the jar api-1.1.5.jar into your classpath. You can download this jar from [maven central here](https://search.maven.org/remotecontent?filepath=com/vmlens/api/1.1.5/api-1.1.5.jar).
The usage of the eclipse plugin [is described here.](https://vmlens.com/help/manual/#run-eclipse)
## 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.1.5
test
com.vmlens
interleave
1.1.5
test
...
...
```
The usage of the maven plugin [is described here.](https://vmlens.com/help/manual/#maven-plugin-configuration-1)
# Documentation
* [JavaDoc](https://vmlens.com/apidocs/api/1.0/)
* [Manual](https://vmlens.com/help/manual/)
# Support
Post an issue in our [issue tracker](https://github.com/vmlens/vmlens/issues/new) or send a message to our [mailing list](https://groups.google.com/forum/#!forum/vmlens-mailing-list).
# Stay in touch
Follow [@ThomasKrieger](https://twitter.com/_thomaskrieger_) and [join our mailing list](https://groups.google.com/forum/#!forum/vmlens-mailing-list).
# Build
To build vmlens, go to vmlens and run
```Shell
mvn clean install
```
You need JDK 11 or higher and a toolchains.xml containing a tag for JDK 8.
Example toolchains.xml:
```XML
jdk
1.8
sun
/path/to/jdk/1.8
```
# License
[Apache License 2.0](https://github.com/vmlens/vmlens/blob/master/LICENSE)