Skip to content

Add link to Bazel+JUnit example; improve description #965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 9, 2025
Merged

Add link to Bazel+JUnit example; improve description #965

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
26f6422
docs: reference a pure Bazel+JUnit5 example that uses Jazzer
oetr Oct 9, 2025
bb3d2ff
docs: fix bad corpus path; add a .gitattributes entry example
oetr Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 18 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,10 +62,15 @@ implementation group: 'com.code-intelligence', name: 'jazzer-junit', version: '<

### Bazel

#### Using rules_fuzzing
Jazzer is supported via [rules_fuzzing](https://github.com/bazelbuild/rules_fuzzing), the official Bazel rules for fuzzing.
For setup instructions, see [the README](https://github.com/bazelbuild/rules_fuzzing#java-fuzzing).

With Jazzer set up, you can start writing fuzz tests and benefit from automated bug discovery and improved code coverage.
#### Using JUnit5 integration

It is also possible to use Jazzer+JUnit5 integration directly in Bazel.
An example project can be found [here](https://github.com/CodeIntelligenceTesting/example-bazel-junit).
The [BUILD](https://github.com/CodeIntelligenceTesting/example-bazel-junit/blob/main/BUILD) file showcases how to set up corpus directories for fuzzing and regression and how to pass arguments to Jazzer and libFuzzer.

## Writing fuzz tests

Expand Down Expand Up @@ -170,20 +175,28 @@ If you see an error saying that `libjvm.so` has not been found, make sure that `

## Directories and files

Jazzer uses two directories to store inputs: the *generated corpus directory* and the *inputs directory*.
Jazzer uses two main directories to store inputs: the *generated corpus directory* and the *inputs directory*.

> [!IMPORTANT]
> If you are using Git and want to add the corpus directories to the repository, mark them as `binary` in your `.gitattributes` file:
>
> ```gitattributes
> src/test/resources/** binary
> .cifuzz-corpus/** binary
> ```

### Generated corpus directory

The *generated corpus directory* is where Jazzer saves inputs that generate new coverage during fuzzing.
It is located in `.cifuzz-corpus/<package>/<FuzzTestClass>/<fuzzTestMethod>`, where `<package>`, `<FuzzTestClass>`, and `<fuzzTestMethod>` correspond to the package name, class name, and method name of the fuzz test, respectively.
For example, if the fuzz test is in the class `src/test/java/com/example/ValidFuzzTestsInputs.java`, method `byteFuzz`, the corpus directory is located in `.cifuzz-corpus/com.example.ValidFuzzTestsInputs/byteFuzz`.
For example, if the fuzz test is in the class `src/test/java/com/example/ValidFuzzTests.java`, method `byteFuzz`, the corpus directory is located in `.cifuzz-corpus/com.example.ValidFuzzTests/byteFuzz`.


### Inputs directory

Any input that triggers a crash during fuzzing is saved to the *inputs directory*.
This directory is derived from the package and class name of the fuzz test.
For example, if the fuzz test is in the class `src/test/java/com/example/ValidFuzzTestsInputs.java`, method `byteFuzz`, the *inputs directory* is located in `src/test/resources/com/example/ValidFuzzTestsInputs/byteFuzz`.
For example, if the fuzz test is in the class `src/test/java/com/example/ValidFuzzTests.java`, method `byteFuzz`, the *inputs directory* is located in `src/test/resources/com/example/ValidFuzzTestsInputs/byteFuzz`.
If this directory does not exist, Jazzer will save crash inputs in the directory from which the tests are executed.


Expand Down Expand Up @@ -225,7 +238,7 @@ If you found something interesting and the information is public, please send a

## Further documentation

* [Arguments and Configuration Options](docs/arguments-and-configuration-options.md)
* [Arguments and configuration options](docs/arguments-and-configuration-options.md)
* [Mutation framework](docs/mutation-framework.md)
* [Advanced techniques](docs/advanced.md)
* [Building Jazzer from source](CONTRIBUTING.md)
Expand Down