Skip to content

Improve documentation #929

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
oetr merged 2 commits into from
Jul 4, 2025
+29 −10
Merged

Improve documentation #929

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5f61b1a
docs: use GitHub Markdown alerts
Marcono1234 Jun 5, 2025
8b4b5db
docs: mention that JUnit inputs should be treated as binary
Marcono1234 Jun 5, 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
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,8 @@ class ParserTests {

A complete Maven example project can be found in [`examples/junit`](examples/junit).

A detailed description of the JUnit integration can be found in the [documentation](docs/junit-integration.md).

### GitHub releases

You can also use GitHub release archives to run a standalone Jazzer binary that starts its own JVM configured for fuzzing:
Expand Down
9 changes: 6 additions & 3 deletions docs/advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@
* [Export Coverage Information](#export-coverage-information)
* [Native Libraries](#native-libraries)

**Note**: These settings apply to the old fuzzing approach using a `fuzzerTestOneInput` method and the native Jazzer binary. They don't work in the new JUnit integration.
> [!NOTE]\
> These settings apply to the old fuzzing approach using a `fuzzerTestOneInput` method and the native Jazzer binary. They don't work in the new JUnit integration.

## Using Jazzer Standalone
There are two ways to use Jazzer standalone: by using the `jazzer` binary or by calling the Jazzer main class directly.
Expand Down Expand Up @@ -117,7 +118,8 @@ Particular stack traces can also be ignored based on their `DEDUP_TOKEN` by pass

### Export Coverage Information

**Note**: This feature is deprecated. The standalone JaCoCo agent should be used to generate coverage reports.
> [!WARNING]\
> This feature is deprecated. The standalone JaCoCo agent should be used to generate coverage reports.

The internally gathered JaCoCo coverage information can be exported in human-readable and JaCoCo execution data format (`.exec`).
These can help identify code areas that have not been covered by the fuzzer and thus may require more comprehensive fuzz targets or a more extensive initial corpus to reach.
Expand Down Expand Up @@ -156,7 +158,8 @@ Jazzer defaults to using the runtimes associated with `clang` on the `PATH`.
If you used a different compiler to compile the native libraries, specify it with `CC` to override this default.
If no compiler is available in your runtime environment (e.g. in OSS-Fuzz) but you have a directory that contains the required sanitier libraries, specify its path in `JAZZER_NATIVE_SANITIZERS_DIR`.

**Note:** On macOS, you may see Gatekeeper warnings when using `--asan` and/or `--ubsan` since these flags cause the native sanitizer libraries to be preloaded into the codesigned `java` executable via `DYLD_INSERT_LIBRARIES`.
> [!NOTE]\
> On macOS, you may see Gatekeeper warnings when using `--asan` and/or `--ubsan` since these flags cause the native sanitizer libraries to be preloaded into the codesigned `java` executable via `DYLD_INSERT_LIBRARIES`.

Sanitizers other than AddressSanitizer and UndefinedBehaviorSanitizer are not yet supported.
Furthermore, due to the nature of the JVM's GC, LeakSanitizer reports too many false positives to be useful and is thus disabled.
Expand Down
3 changes: 2 additions & 1 deletion docs/common.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
* [Parallel Execution](#parallel-execution)
* [Autofuzz Mode](#autofuzz-mode)

**Note**: These settings apply to the old fuzzing approach using a `fuzzerTestOneInput` method and the native Jazzer binary. They don't work in the new JUnit integration.
> [!NOTE]\
> These settings apply to the old fuzzing approach using a `fuzzerTestOneInput` method and the native Jazzer binary. They don't work in the new JUnit integration.

## Recommended JVM Options

Expand Down
25 changes: 19 additions & 6 deletions docs/junit-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,9 @@ existing findings or corpus entries.

The mutation framework is located in the `com.code_intelligence.jazzer.mutation` package.

**Note**: If a fuzz function still expects a single `FuzzedDataProvider` or `byte[]` parameter, the mutation framework
will not be used!
> [!NOTE]\
> If a fuzz function still expects a single `FuzzedDataProvider` or `byte[]` parameter, the mutation framework
> will not be used!

The example below shows how to use complex data types in a fuzz test. Any supported type can be used as a parameter of a
fuzz test. The mutation framework will automatically create and mutate the parameters accordingly.
Expand Down Expand Up @@ -84,8 +85,9 @@ It is sometimes helpful to provide additional information about the Fuzz Test
parameters, e.g. to specify the range of integers, or the maximum length of a
string. This is done using annotations directly on the parameters.

**Note**: Annotations are used on best effort basis, meaning that the fuzzer
will try to honor specified constraints, but can not guarantee it.
> [!NOTE]\
> Annotations are used on best effort basis, meaning that the fuzzer
> will try to honor specified constraints, but can not guarantee it.

All annotations reside in the `com.code_intelligence.jazzer.mutation.annotation`
package.
Expand Down Expand Up @@ -271,8 +273,9 @@ simplify the construction of complex objects.
the target class. In this situation the `builder` itself is passed into the
constructor of the target class.

**Note**: These pattern are generated by the commonly used
[Lombok](https://projectlombok.org/) `@Builder` and `@SuperBuilder` annotations.
> [!NOTE]\
> These pattern are generated by the commonly used
> [Lombok](https://projectlombok.org/) `@Builder` and `@SuperBuilder` annotations.

The examples below use [Lombok](https://projectlombok.org/) to generate
appropriate `builder` classes:
Expand Down Expand Up @@ -362,6 +365,10 @@ value (`true`, `1`, `yes`)) and in regression mode (when `JAZZER_FUZZ` is not se

JUnit will call the following methods for each test marked with `FuzzTest`.

> [!NOTE]\
> In fuzzing mode, only a single fuzz test is executed per test run
> (see [#599](https://github.com/CodeIntelligenceTesting/jazzer/issues/599) for details).

#### `evaluateExecutionCondition`

The first call to this test will determine if the test should be run at all. In fuzzing mode, we only allow one test to
Expand Down Expand Up @@ -426,6 +433,12 @@ The tests from the resources directory are gathered by `walkInputs`. This will l
JUnit will use the file's name as the name of the test case for its reporting. It also accepts .jar files where it will
search with the given directory in the jar.

> [!IMPORTANT]\
> When adding these inputs files to a Git repository, consider creating a `.gitattributes` file containing
> `src/test/resources/** binary` or similar to explicitly mark the files as binary files. Otherwise Git might
> erroneously consider them text files, misinterpret bytes as line terminators and convert them on checkout.
> This would change the content of the inputs files and can lead to unexpected behavior.

##### Corpus

The corpus kept in `.cifuzz-corpus/<test class name>/<test method name>` holds any inputs that libfuzzer found worth
Expand Down