| ~~~~~~~ |
| Fuzzing |
| ~~~~~~~ |
| |
| .. include:: prologue.rst |
| |
| Principle |
| ========= |
| |
| BRLTTY has some support for testing it through fuzzing, i.e. feeding it with |
| more or less random content, to check that it does not fall into pieces. |
| |
| Building |
| -------- |
| |
| Building with fuzzing support is |
| |
| CC=clang ./configure --enable-api-fuzzing |
| |
| (Fuzzing is only supported with the clang compiler) |
| |
| This will also enable the address and undefined-behavior sanitizers. |
| |
| Running |
| ------- |
| |
| To start a fuzzing session, one has to set the fuzz BrlAPI parameter, for |
| instance to start 1000 fuzzing loops: |
| |
| ./run-brltty -b xw -x no -A fuzz=1000 -n -e |
| |
| It can be useful to try different fuzzing seeds with: |
| |
| ./run-brltty -b xw -x no -A fuzz=1000,fuzzseed=1234 -n -e |
| |
| The initial steps of BrlAPI connections are not fuzzed by default, so the fuzzer |
| does not have to get it right before fuzzing the rest of the protocol. To fuzz |
| these initial steps, one can use: |
| |
| ./run-brltty -b xw -x no -A fuzz=1000,fuzzhead=on -n -e |
| |
| Conversely, one can concentrate the fuzzing on the writeText operation only (in |
| latin1) with: |
| |
| ./run-brltty -b xw -x no -A fuzz=1000,fuzzwrite=on -n -e |
| |
| And in utf8: |
| |
| ./run-brltty -b xw -x no -A fuzz=1000,fuzzwriteutf8=on -n -e |
| |
| Reproducing |
| ----------- |
| |
| Once a bug is detected by the fuzzer, it emits a crash file. One can reproduce |
| the behavior with: |
| |
| ./run-brltty -b xw -x no -A crash=crash-da39a3ee5e6b4b0d3255bfef95601890afd80709 -n -e |
| |
| and use gdb etc. at will to understand the bug, and eventually check when it is |
| fixed. |
