Tutorial
NOTE: Users have reported problems with the eclipse plugin. We are
in the process of fixing this problem. In the meanwhile, we recommend
using the command-line interface.
We will use Eclat to generate test inputs for a class that implements a stack:
BoundedStack.java. The class has
a small initial test suite BoundedStackJunitTest.java.
We will use Eclat to help us improve the existing test suite, and in
the process, discover errors in the implementation.
Setup
| Command-line | Eclipse |
- Go the the directory where you downloaded eclat.jar.
cd directory-where-you-downloaded-eclat-jar
- Extract the example files from eclat.jar.
(all in one line:)
jar xf eclat.jar examples/ubs/BoundedStack.java examples/ubs/BoundedStackJunitTest.java
- Move to the examples directory.
cd examples
- Compile the example sources.
javac ubs/*.java
|
-
Download and unzip example.zip.
It contains two Java files:
ubs/BoundedStack.java
and
ubs/BoundedStackJunitTest.java.
-
Create a new Java project and import the sources from
example.zip. Get the project to compile without error.
|
Now we're ready to run Eclat. We will ask Eclat to test the class
(ubs/BoundedStack.java) using the example execution
(ubs.BoundedStackJunitTest). In addition, we will ask for a
regression suite to be generated.
Run Eclat
| Command-line | Eclipse |
(all in one line:)
java eclat.textui.Main generate-inputs --create-regression-suite --test ubs/BoundedStack.java ubs.BoundedStackJunitTest
|
- Open the run configurations window (Run -> Run...). Create a new Eclat
configuration by double-clicking the "Eclat" configuration.
- Add BoundedStack.java to the list of "Test sources" under the "Test
sources" tab.
- Switch to the "Main" tab, and specify
ubs.BoundedStackJunitTest as the main class.
- Switch to the "Eclat" tab, and check the "Create regression suite" box.
- Press the "Run" button to start Eclat. You will see Eclat
output progress information to the Console window.
- When Eclat is finished, press F5 on the package explorer. It will update the
resource tree with Eclat's results.
|
As a result of this command, Eclat creates two directories: eclat-src and eclat-misc.
eclat-src: tests for BoundedStack
The important directory is
eclat-src: it contains the JUnit suites that Eclat generated
to test the stack. Let's start by compiling the files in the directory.
| Command-line | Eclipse |
(all in one line:)
find ./eclat-src -name *.java | xargs javac
|
- Add eclat-src as a source folder (right click on the
folder eclat-src and select "Build
Path" -> "Add to Build Path," answering yes to any questions
about redefining the output folder).
- Add daikon.jar to the project's build path.
You have already downloaded this jar file as part of the plugin
(for example, in my computer, the jar is under
C:\Program Files\eclipse\plugins\eclatPlugin_1.0.0\lib.
You can add the jar file as an external jar.
- At this point, all the classes under eclat-src should
compile without error.
|
Package eclatgen contains all Eclat-generated JUnit
classes (other packages contain helper classes).
Package eclatgen.problems contains a JUnit test suite
with failing tests that are deemed problematic (fault-revealing). To
see the failures, run the single class in this package,
eclatgen.BoundedStackEclatTest.
| Command-line | Eclipse |
(all in one line:)
java -classpath eclat-src:$CLASSPATH eclatgen.problems.BoundedStackEclatTest
|
In the package explorer, right-click on the class
eclatgen.problems.BoundedStackEclatTest, and do "Run As" ->
"JUnit Test."
|
Inspect the failures. You can follow the stack trace to the root of
the failure. One failure uncovers an error in the implemenatation of
equals, which throws an exception when comparing against
null. Another failure uncovers an error in the pop method,
which pops a stack even if it is empty, making the stack pointer
negative. The two remaining failures are false alarms: they do
not uncover an error.
Package eclatgen.regression contains a JUnit test
suite with passing tests that comprise a regression suite of the
stack. To run the regression suite, run the class in the package
containing a main method (in this case,
eclatgen.regression.EclatRegressionSuite):
| Command-line | Eclipse |
(all in one line:)
java -classpath eclat-src:$CLASSPATH eclatgen.regression.EclatRegressionSuite
|
In the package explorer, right-click on the class
eclatgen.regression.EclatRegressionSuite, and do "Run As" ->
"JUnit Test."
|
This time, you should see about 1000 tests execute without
failure. Since the class hasn't been modified, there is no chance of
a regression error occurring.
eclat-misc: useful non-Java files
The directory eclat-misc contains
non-Java files related to the tested class. You will find these useful
when trying to understand why Eclat generated (or failed to generate)
good test cases.
- BoundedStackJunitTest.inv.gz is the invariant file generated by Daikon (see
the Daikon manual).
- BoundedStackJunitTest.allinputs.txt.zip contains a
human-readable listing of all the inputs that Eclat generated,
sorted by round. This includes inputs that were generated but not
deemed useful, such as illegal inputs.
- inputs.serialized also contains all the inputs
generated by Daikon, in serialized form.
(Code for the bounded stack example due to D. Stotts, M.
Lindsey, and A. Antley. An informal formal method for systematic
JUnit test case generation. In XP/Agile Universe, pages 131-143,
Aug. 2002.)
|
