docs/ARCHITECTURE: describe fuzzer locations and use

This commit is contained in:
Zbigniew Jędrzejewski-Szmek
2022-05-05 18:35:10 +02:00
parent 680f2fb39d
commit c04361d725

View File

@@ -91,7 +91,12 @@ and generally safe to run on the host without side effects.
Ideally, every module in `src/basic/` and `src/shared/` should have a
corresponding unit test under `src/test/`, exercising every helper function.
## Fuzzer test cases
## Fuzzing
Fuzzers are a type of unit tests that execute code on an externally-supplied
input sample. Fuzzers are called `fuzz-*`. Fuzzers for `src/basic/` and
`src/shared` live under `src/fuzz/`, and those for other parts of the codebase
should be located next to the code they test.
Files under `test/fuzz/` contain input data for fuzzers, one subdirectory for
each fuzzer. Some of the files are "seed corpora", i.e. files that contain
@@ -102,6 +107,16 @@ When adding new input samples under `test/fuzz/*/`, please use some
short-but-meaningful names. Names of meson tests include the input file name
and output looks awkward if they are too long.
Fuzzers are invoked primarily in three ways: firstly, each fuzzer is compiled
as a normal executable and executed for each of the input samples under
`test/fuzz/` as part of the test suite. Secondly, fuzzers may be instrumented
with sanitizers and invoked as part of the test suite (if `-Dfuzz-tests=true`
is configured). Thirdly, fuzzers are executed through fuzzing engines that try
to find new "interesting" inputs through coverage feedback and massive
parallelization; see the links for oss-fuzz in [Code
quality](https://systemd.io/CODE_QUALITY). For testing and debugging, fuzzers
can be executed as any other program, including under `valgrind` or `gdb`.
# Integration Tests
Sources in `test/TEST-*` implement system-level testing for executables,