Run a Fuzz Test With CI Fuzz
You can build and execute a Fuzz Test with the cifuzz run
command:
cifuzz run <fuzz test> [--option...] [--] [<build system argument>...]
Fuzz Test Argument
The name and syntax of the Fuzz Test argument are dependent on the build system:
- CMake
- Bazel
- Maven/Gradle
- NodeJS
Argument | Description |
---|---|
<fuzz test> | Name of the Fuzz Test defined in the add_fuzz_test command in your CMakeLists.txt |
Argument | Description |
---|---|
<fuzz test> | Name of the cc_fuzz_test target defined in your BUILD.bazel fileCan be written as a relative or absolute Bazel label |
Argument | Description |
---|---|
<fuzz test>::<method name> | Name of the class containing the Fuzz Test and the name of the Fuzz Test |
Argument | Description |
---|---|
<fuzz test>:<test name> | Regex pattern that matches against all paths containing Fuzz Test files |
Command completion
Command completion for the <fuzz test>
argument is immediately supported for Bazel, Maven, Gradle and NodeJS.
In the case of CMake, it is only supported after the Fuzz Test was built or the command cifuzz reload
was called.
Command completion for other build systems are not supported.
Options
The cifuzz run
command supports the following command specific options:
Flag | Description |
---|---|
--build-command <command> | Command to build the Fuzz Test for other build systems |
--build-jobs uint[=0] | Maximum number of concurrent processes to use when building If argument is omitted the native build tool's default number is used |
--build-only | Only build the Fuzz Test and don't execute it |
--clean-command <command> | The command to clean the Fuzz Test and its dependencies for other build systems |
--dict <path/to/file> | A file containing input language keywords or other interesting byte sequences This flag is only used if no default dictionary is found for the Fuzz Test See https://llvm.org/docs/LibFuzzer.html#dictionaries |
--engine-arg <argument> | Command-line argument to pass to the fuzzing engine See https://llvm.org/docs/LibFuzzer.html#options This flag can be used multiple times Not supported for Node.js projects |
--fail-fast | Exit the fuzzing campaign as soon as a Finding is found |
--interactive | Toggle interactive prompting in the terminal (default=true) |
--json | Print output as JSON |
--max-fuzzing-duration <duration> | Maximum time to run all Fuzz Tests, e.g. "30m", "1h". The default is 10 minutes Example: if you run three Fuzz Tests with --max-fuzzing-duration=3m ,each Fuzz Test will be fuzzing for maximum 1 minute. To keep running indefinitely, set the value to 0. |
--min-severity <severity> | Minimum severity of Findings. If a Finding was found with this severity or higher, the process will exit with status code 99. Any Finding with a lower severity will only be marked as a warning |
--project-dir <dir> | The project root which is the parent for all the project sources Defaults to the directory containing the cifuzz.yaml |
--prune-corpus-only | Prune redundant corpus entries that produce the same coverage and quit |
--prune-shard-size <size> | Number of corpus inputs in each shard when pruning the corpus with--prune-corpus-only flag |
--regression-only | Run configured Fuzz Tests in regression mode, which only runs the test against previous Findings and existing test cases (no fuzzing is done) |
-r, --resolve | Argument of the command is a path to a source file instead of a test identifier. The path can be either absolute or relative to the current working directory and will be resolved to the identifier of the corresponding Fuzz Test. |
-s, --seed-corpus <dir> | A directory containing sample inputs used as seeds for fuzzing the code under test This is used in addition to inputs found in the inputs directory of the Fuzz Test This flag can be used multiple times |
--with-coverage | Follow up with code coverage for the Fuzz Test |
All supported global options are documented in Learn CI Fuzz.
Build System Arguments
Additional arguments for CMake, Bazel, Maven and Gradle can be passed after a --
at the end of the command. All other
options have to be defined before.
- CMake
- Bazel
- Maven
Example
cifuzz run my_fuzz_test -- -G Ninja
Example
cifuzz run src:my_fuzz_test -- --sandbox_debug
Example
cifuzz run com.example.FuzzTestCase::myFuzzTest -- -Dcheckstyle.skip