Add FUZZ_TESTING.md

This describes how I did the AFL testing of libvilistextum

1 files changed, 37 insertions, 0 deletions

diff --git a/FUZZ_TESTING.md b/FUZZ_TESTING.md
new file mode 100644
index 00000000..3cc0b2a8
--- /dev/null
+++ b/FUZZ_TESTING.md
@@ -0,0 +1,37 @@
+# Fuzz testing
+
+## libvilistextum
+
+Install american fuzzy lop, however you do that on your OS.
+
+Rebuild using `afl-gcc`:
+
+```
+rm -rf builddir
+CC=afl-gcc meson builddir
+ninja -C builddir
+```
+
+Now run `afl-fuzz`:
+
+```
+afl-fuzz -m 512 -x libraries/libVilistextum/dictionaries/xml.dict -i libraries/libVilistextum/inputs -o output -- ./builddir/libraries/libVilistextum/vilistextum_main
+```
+
+This should take the inputs in `libraries/libVilistextum/inputs`, and start making random tests (using a little
+help from the XML dictionary). If you get any crashes or hangs, there will be
+output in `output/crashes` or `output/hangs`.
+
+For crashes, Valgrind can give you a backtrace:
+
+```
+valgrind --track-origins=yes ./builddir/libraries/libVilistextum/vilistextum_main < output/crashes/[failed-test]
+```
+
+For hangs, run `gdb` and then cancel it:
+
+```
+gdb ./builddir/libraries/libVilistextum/vilistextum_main
+(gdb) run < < output/crashes/[failed-test]
+# type ctrl+c, then bt, or use other tools like print and up/down
+```