Eclat logo Eclat 1.1
Program Analysis Group * CSAIL * MIT

Eclat Manual (version 1.1, released May 6, 2005).

Contents



Eclat Commands

Eclat's entry point is the class eclat.textui.Main, which takes a command and a list of arguments.
java eclat.textui.Main <command> <command-options> <command-arguments>

The most important command is generate-inputs. This command generates unit tests for classes. Below is a list of the commands. You can also see this documentation with the help command:

java eclat.textui.Main help

generate-inputs

USAGE

generate-inputs OPTIONS EXEC_CLASS EXEC_CLASS_ARGS

Where:

1. At least one `--test' option is present.
2. EXEC_CLASS is the name of a class that declares a main method (include package name).
3. EXEC_CLASS has already been compiled and is in your classpath.
4. EXEC_CLASS_ARGS are the arguments passed to the executable class.
Note: Eclat only attempts to construct new objects for those classes specified as test classes (with the '--test' option). Thus, for example, if you are testing a graph class Graph whose nodes are of type Node, you should specify both classes as test classes, so Eclat can construct Node objects to use in building interesting graphs.
SUMMARY

Generates test inputs for the classes specified with the '--test' option. The inputs exhibit behavior that deviates from the behavior observed when running the program EXEC_CLASS. The inputs are heuristically determined as potentially fault-revealing.

INPUT

An executable class (plus any arguments its takes), and a list of source files containing the classes to be tested.

OUTPUT

A JUnit test class containing new inputs for the tested classes, and a text file containing all the inputs generated.

EXAMPLE

java eclat.textui.Main generate-inputs --test ubs/BoundedStack.java mypackage.MyBoundedStackProgram

OPTIONS

Test targets

--test FILE.java
Generate inputs for the class(es) in FILE.java. This option must be given at least once, and may be given more than once.
--hints-file FILE.java
Use constants found in FILE.java when creating inputs. This option can be given more than once.
--detect-properties FILE.java
Include the classes declared in FILE.java when detecting properties.

Invariant detection

--use-existing-inv-file FILE.inv.gz
Do not run the runnable command, and do not run dynamic analysis. Instead, use the given invariant file.
--use-instrumented-dir DIR
Skip invariant detection and instrumentation altogether, and assume that property-checking-instrumented classes are already in director DIR.
--name-resulting-inv-file FILE
Name to give the resulting invariant file. The invariant file will be the result of "new java.io.File(FILE)".
--nesting-depth N
Depth to which to examine structure components (default=2).
--stop-after-ppt N
Will stop observing values after N program points traversed (speeds up property analysis).
--process-only-first-nth-percent-of-trace N
Will use only the first N percent of the program execution to derived invariants.

Files created by Eclat

--create-regression-suite
Create JUnit regression suite from normal inputs.
--do-not-remove-scratch-dir
Do not remove scratch dir containing temporary artifacts such as trace file, instrumented classes, etc. The default is to remove the scracth dir before exiting.
--src-dir dir
Write resulting JUnit tests to dir (default = eclat-src)
--output-dir dir
Write all results to dir (default = current directory)
--junit-classname TESTCLASS
Resulting JUnit test suite will be named TESTCLASS.
--text-output FILENAME
Text file containing all inputs will be named FILENAME.
--no-text-output
Don't output a text file containing all inputs generated.
--verbose-results
Resulting JUnit test suite will contain comments with lots of information about input behavior.
--no-junit-output
Don't output a JUnit class.
--serialized-output FILENAME
Output a file containing all the inputs generated, in serialized form. Output will go to FILENAME.

Progress reporting as Eclat executes

--verbose
Print copious information about Eclat's progress to stdout.
--debug
For developers: as Eclat executes, LOTS of information will be printed to stdout.

Generation parameters

--num-rounds N
Do N rounds of generation (default = 4)
--invoc-per-round N
On each round, try to create N new invocations of each method. (default = 100)
--method-only-regexp R
Use only methods whose names match regexp R. The syntax of R is the one defined by java.util.regex.
--method-omit-regexp R
Use only methods whose names do NOT match regexp. The syntax of R is the one defined by java.util.regex.
--pool-addition-policy POLICY
Policy for adding inputs to the pool. Inputs are added after each round of input creation. Default is "normal". POLICY is one of the following: (1) "all" means add all inputs. (2) "normal" means add inputs classified as normal. (3) "normal-no-vios" means add inputs classified as normal which violated no model properties.
--generation-strategy STRATEGY
Strategy for generating inputs during each round. At each round of generation, only one strategy is chosen. Default is "random". STRATEGY is one of the following: (1) "random" -- for every round, create random method invocations using. the values found in the current pool. (2) "exhaustive" -- for every round, create all method invocations that are possible using the values found in the current pool (to avoid exponential blowup, see the time-limit-millis option). (3) "hybrid" -- for each round of generation, a strategy is chosen as follows. If the number of inputs using exhaustive generation is less than the limit hybrid-generation-input-limit then use exhaustive generation. Otherwise, use random generation.
--hybrid-generation-input-limit LIMIT
Default is 2000. This option is only meaningful if the option generation-strategy has been set to "hybrid". See description of that option.
--time-limit-millis LIMIT
Default is no limit, i.e. infinite limit. Spend no more than LIMIT milliseconds generating inputs.
--reduction-strategy STRATEGY
Strategy for reducing (choosing a subset of) the inputs before prenseting them to the user. Default is "use-all-properties". STRATEGY is one of the following: (1) "use-all-properties" -- partition inputs based on the set of properties that they violated, and choose one input from each partition. (2) "use-important-properties" -- like previous, but only consider high-confidence properties.
--classifier-confidence-threshold THRESHOLD
Confidence trehold above which properties are considered important by the classifier. A value between 0 and 1. Default = 0.5.

Miscellaneous

--java-arg JAVA_ARG
Will use JAVA_ARG when calling Java on a subprocess. Can be give more than once: give this command once for each java argument you want added.

help

USAGE

help

SUMMARY

Displays a help message.

INPUT

None.

OUTPUT

A help message is printed to stdout.


Frequently asked questions

This section is under construction.

Send comments or questions to Eclat's mailing list.

Valid HTML 4.0!

Last modified: June 09 2005 19:05:44.