JQF Maven Plugin

The JQF maven plugin allows you to fuzz your programs simply using the command mvn jqf:fuzz. This means that you do not have to clone the JQF repo and run shell scripts. Once you have written a JQF test using a dependency on jqf-fuzz for the API, you are ready to use the plugin.

Note: The JQF Maven Plugin launches the Zest engine by default.

Setup

Add this in your pom.xml file:

<build>
    <plugins>
        <plugin>
            <groupId>edu.berkeley.cs.jqf</groupId>
            <artifactId>jqf-maven-plugin</artifactId>
            <version>1.1</version>
        </plugin>
    </plugins>
</build>

Note: You may want to double-check what is the latest released version, since this wiki page may go out of date. Use the version string after the prefix "jqf-" (e.g. if the release is "jqf-1.1" then use "1.1" as version).

Fuzzing

Run the command:

mvn jqf:fuzz -Dclass=<fully-qualified-class-name> -Dmethod=<method-name>

Where the class and method names are for the target you are trying to fuzz. See Writing a JQF test.

For example, in the JQF examples project directory,

mvn jqf:fuzz -Dclass=edu.berkeley.cs.jqf.examples.closure.CompilerTest -Dmethod=testWithGenerator

The results of fuzzing are usually saved in a directory such as target/fuzz-results/<class-name>/<method-name>, but this can be changed (along with many other things such timeouts and which classes to include/exclude from instrumentation). To get a full list of configuration commands, ask Maven to describe the plugin's options:

mvn help:describe -Dplugin=jqf -Ddetail

Reproducing tests

Once the fuzzing stops due to a timeout or a CTRL+C, you can reproduce a generated input (such as a failure). Run the command:

mvn jqf:repro -Dclass=<fully-qualified-class-name> -Dmethod=<method-name> -Dinput=<file-or-directory-name>

For example,

mvn jqf:repro -Dclass=edu.berkeley.cs.jqf.examples.closure.CompilerTest -Dmethod=testWithGenerator -Dinput=target/fuzz-results/edu.berkeley.cs.jqf.examples.closure.CompilerTest/testWithGenerator/corpus/id_000028

or

mvn jqf:repro -Dclass=edu.berkeley.cs.jqf.examples.closure.CompilerTest -Dmethod=testWithGenerator -Dinput=target/fuzz-results/edu.berkeley.cs.jqf.examples.closure.CompilerTest/testWithGenerator/corpus

Other Configurations

To list all the configuration options supported by the JQF Maven Plugin, run:

mvn help:describe -Dplugin=jqf -Ddetail

The most commonly used ones will include:

• -Dexcludes=<list>: Comma-separated list of fully-qualified class-name prefixes to exclude from coverage instrumentation (e.g. org.apache.commons). Default is empty.
• -Dincludes=<list>: Comma-separated list of fully-qualified class-name prefixes to forcibly include, even if they match an exclude (e.g. org.apache.commons.io). Default is empty.
• -Dtime=<timeout> (jqf:fuzz only): Stop fuzzing after a timeout. Examples of timeouts include 30s, 60m or 24h. Default is empty, implying no timeout.
• -Dblind (jqf:fuzz only): Do not save any inputs during fuzzing. Every input is generated randomly from scratch instead of by mutation. This is equivalent to running only junit-quickcheck, as it does not rely on a feedback-directed search.
• -DlogCoverage=<file> (jqf:repro only): Output file to dump coverage info (e.g. coverage.out). Default is empty, implying no dump file.