<commit_before># How to run the fuzz tests

1. Build Realm with the AFL-instrumented compilers.

   On Linux:

   ```
   $ CXX=afl-g++ make check-debug-norun COMPILER_IS_GCC_LIKE=yes
   ```

   Or on Mac OS X:

   ```
   $ CXX=afl-clang++ make check-debug-norun COMPILER_IS_GCC_LIKE=yes
   ```

2. Execute the fuzz tester:

   ```
   $ cd test/fuzzy
   $ afl-fuzz -i testcases -o findings ./fuzzy-tests-dbg @@
   ```

3. When AFL detects crashes, it records the input files that it used under `findings/crashes`.
   To debug the crash:

   ```
   $ gdb ./fuzz-group-gdb
   > r --log findings/crashes/<id>
   ```

    Or using lldb:

    ```
    $ lldb ./fuzz-group-dbg -- --log findings/crashes/<id>
    > r
    ```


The `@@` tells AFL where to put command-line arguments (autogenerated input files).
Put specially designed test cases under `testcases`.

The fuzz test can also be run with release mode code to avoid hitting asserts.

See also [AFL's README](http://lcamtuf.coredump.cx/afl/README.txt).<commit_msg>Changed fuzzer README into explaining how to use this the most easy way. Consider adding more detailed info.<commit_after># How to Run the Fuzz Tests

## The Simple Way

`sh simple_start.sh`

Builds `realm-core` and the fuzz target with `afl-g++` on Linux (or `afl-clang++` on OS X) and starts N instances of `afl-fuzz`, where N is the number of logical CPU processors.

`sh simple_stop.sh`

Kills the running `afl-fuzz` instances and converts any found crashes and / or hangs into `.cpp` unit tests, stored in `findings/cpp_unit_tests/`

Turn these into regular unit tests (most easily done in `test_lang_bind_helper.cpp`) to debug further.

## See Also

[AFL's README](http://lcamtuf.coredump.cx/afl/README.txt)
{'fraction_non_alphanumeric': 0.11342592592592593, 'fraction_numerical': 0.001736111111111111, 'mean_word_length': 3.311720698254364, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5133451', 'n_tokens_mistral': 617, 'n_tokens_neox': 592, 'n_words': 209}