Join GitHub today
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
cJUnit - a JUnit extension for concurrent unit tests About ===== Have you ever attempted to write multi-threaded unit tests? Did you run them repeatedly in the hope to detect concurrency bugs by chance? But you never knew how many times you should repeat such a unit test to make sure that the unit under test delivers the expected results independently from the thread interleavings? cJUnit is an extension to the well-known JUnit unit testing framework to support concurrent unit tests, i.e. to automatically run such tests in all relevant different thread interleavings. This way concurrency bugs in unit tests are detected reliably, not just by chance, and, more importatly, you can verify that a concurrent unit test produces the expected results independently from the scheduling of its threads. Build ===== To build cJUnit from source you'll need - Java 1.6 - ant 1.7 (or later) All other software dependencies are included in the cJUnit source tree under the 'lib/' directory, namely: - JUnit: the well-known unit testing framework for Java (release 4.5) - Java PathFinder (JPF): the model checker used behind the scenes in cJUnit (from SVN revision r1539) - JPF's dependencies: BCEL, the Bytecode Engineering Library (release 5.2) - hamcrest assertion library (version 1.3RC0) (If you want to use different versions from any of these, please refer to the Compatibility section below.) You can build cJUnit by running ant all This will create 'cjunit-all.jar', which includes everything needed to run concurrent unit tests: cJUnit and all its dependencies listed above and the javadoc of cJUnit's API. Add this jar to your classpath, and test the installation by running java org.junit.runner.JUnitCore de.fzi.cjunit.AllTests de.fzi.concurrentmatchers.AllTests Use === From an IDE ----------- Modern Java IDEs like eclipse or NetBeans already contain a JUnit plugin. Although these plugins do not provide direct support for concurrent unit tests, it is still possible to use cJUnit with them. - Include 'cjunit-all.jar' in the project's build path. - (optional) Set the location of cJUnit's javadoc. The javadoc for cJUnit's API for concurrent unit tests is included under the 'doc/' directory within the 'cjunit-all.jar' archive. - (optional) Filter out cJUnit stack frames from failure stack traces with the following filter pattern: 'de.fzi.cjunit.jpf.*' - (optional) Specify the source code location, see below. - Write concurrent unit tests. Test classes containing concurrent unit tests should be annotated with @RunWith(ConcurrentRunner.class). - Run unit tests using the IDE's JUnit plugin as usual. From the command line --------------------- cJUnit can be used from the command line the same way as JUnit. - Include 'cjunit-all.jar' in your CLASSPATH. - (optional) Specify the source code location, see below. - Write concurrent unit tests. Test classes containing concurrent unit tests should be annotated with @RunWith(ConcurrentRunner.class). - Run unit tests as usual: java org.junit.runner.JUnitCore <tests> - (alternatively) Run unit tests with cJUnit the same way as with JUnit: java de.fzi.cjunit.ConcurrentJUnit <tests> In this case it is not necessary to annotate the test class with @RunWith(ConcurrentRunner.class), but then the concurrent unit tests could only be run with cJUnit from the command line, and not from an IDE plugin. Specifying source code location ------------------------------- If a concurrency bug is detected in a concurrent unit test, the execution path triggering the bug will be printed. To include the actual source code in this execution path, the location of source code files has to be specified. Note, that specifying the source code location is not necessary to run concurrent unit tests, but the execution path will be of much less use when omitted. To specify the source code locations place a file named 'jpf.properties' in the directory where cJUnit is invoked from (e.g. the project root) with the following contents: vm.sourcepath=<srcpath1,srcpath2,...> i.e. 'vm.sourcepath=' followed by a comma separated list of paths containing the source code files. For example, if the source files are under the directories 'src/main' and 'src/test', then the file should contain the following line: vm.sourcepath=src/main,src/test Compatibility ============= JUnit ----- cJUnit works with JUnit releases 4.5 or later. However, the following JUnit features are not supported or are broken: - @BeforeClass and @AfterClass annotations are not supported. Use of any of these annotations in concurrent test classes will cause an InitializationError exception. - Parallel execution (introduced in JUnit release 4.6) of concurrent unit tests will break. - @Rules (introduced in JUnit release 4.7) will break. JPF --- cJUnit works with the provided JPF version (r1539). Perhaps with other revisions, too, but API and configuration changes are far too frequent. If you manage to compile cJUnit with a different JPF revision, you might want to run the test classes in the de.fzi.cjunit.jpf.assumptions package, one at a time. BCEL ---- cJUnit (or rather JPF) works with BCEL release 5.2, which was released more than 4 years ago, and not much has happened since then. hamcrest -------- cJUnit works with hamcrest versions 1.3RC0 or later. There are various compile and runtime issues with previous versions. License ======= cJUnit is licensed under the terms of the Common Public License v1.0. The license terms can be found in the LICENSE file. cJUnit's source and binary distributions include other software components cJUnit depends on. These software components are subject of their own licenses, respectively, which are included in the distribution in the files LICENSE.<component> (e.g. LICENSE.JUnit). Acknowledgements ================ Parts of cJUnit were developed within the JEOPARD (Java Environment for Parallel Realtime Development; http://www.jeopard.org/) research project, which received funding from the European Union's Seventh Framework Programme under grant agreement No. 216682.