ceph/src/isa-l/doc/test.md

   1 # ISA-L Testing
   2
   3 Tests are divided into check tests, unit tests and fuzz tests. Check tests,
   4 built with `make check`, should have no additional dependencies. Other unit
   5 tests built with `make test` may have additional dependencies in order to make
   6 comparisons of the output of ISA-L to other standard libraries and ensure
   7 compatibility. Fuzz tests are meant to be run with a fuzzing tool such as [AFL]
   8 or [llvm libFuzzer] fuzzing to direct the input data based on coverage. There
   9 are a number of scripts in the /tools directory to help with automating the
  10 running of tests.
  11
  12 ## Test check
  13
  14 `./tools/test_autorun.sh` is a helper script for kicking off check tests, that
  15 typically run for a few minutes, or extended tests that could run much
  16 longer. The command `test_autorun.sh check` build and runs all check tests with
  17 autotools and runs other short tests to ensure check tests, unit tests,
  18 examples, install, exe stack, format are correct. Each run of `test_autorun.sh`
  19 builds tests with a new random test seed that ensures that each run is unique to
  20 the seed but deterministic for debugging. Tests are also built with sanitizers
  21 and Electric Fence if available.
  22
  23 ## Extended tests
  24
  25 Extended tests are initiated with the command `./tools/test_autorun.sh
  26 ext`. These build and run check tests, unit tests, and other utilities that can
  27 take much longer than check tests alone. This includes special compression tools
  28 and some cross targets such as the no-arch build of base functions only and
  29 mingw build if tools are available.
  30
  31 ## Fuzz testing
  32
  33 `./tools/test_fuzz.sh` is a helper script for fuzzing to setup, build and run
  34 the ISA-L inflate fuzz tests on multiple fuzz tools. Fuzzing with
  35 [llvm libFuzzer] requires clang compiler tools with `-fsanitize=fuzzer` or
  36 `libFuzzer` installed. You can invoke the default fuzz tests under llvm with
  37
  38     ./tools/test_fuzz.sh -e checked
  39
  40 To use [AFL], install tools and system setup for `afl-fuzz` and run
  41
  42     ./tools/test_fuzz.sh -e checked --afl 1 --llvm -1 -d 1
  43
  44 This uses internal vectors as a seed. You can also specify a sample file to use
  45 as a seed instead with `-f <file>`. One of three fuzz tests can be invoked:
  46 checked, simple, and round_trip.
  47
  48 [llvm libFuzzer]: https://llvm.org/docs/LibFuzzer.html
  49 [AFL]: https://github.com/google/AFL