~~~~~~~
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.