reword fuzz README.md

Author: chrisjsewell

tests/fuzz/README.md

@@ -1,39 +1,41 @@
-# Fuzzing by way of OSS-Fuzz
+# OSS-Fuzz integration
 
-Fuzzing set up that is run by OSS-Fuzz. The relevant files in the OSS-Fuzz
-repository is [here](https://github.com/google/oss-fuzz/tree/master/projects/markdown-it-py).
+In principle, core Markdown parsing is designed to never except/crash on any input,
+and so [fuzzing](https://en.wikipedia.org/wiki/Fuzzing) can be used to test this conformance.
+This folder contains fuzzers which are principally run downstream as part of the <https://github.com/google/oss-fuzz> infrastructure.
 
-The fuzzers require the [Atheris](https://pypi.org/project/atheris/) package.
-You need this package to run the fuzzers locally (i.e. non oss-fuzz).
+Any file that matches `fuzz_*.py` in this repository will be built and run on OSS-Fuzz
+(see <https://github.com/google/oss-fuzz/blob/master/projects/markdown-it-py/build.sh>).
 
-## Building by way of OSS-Fuzz
-The following steps will build the fuzzers using the OSS-Fuzz infrastructure:
-```
-git clone https://github.com/google/oss-fuzz
-cd oss-fuzz
-python3 infra/helper.py build_fuzzers markdown-it-py
+See <https://google.github.io/oss-fuzz/advanced-topics/ideal-integration> for full details.
 
-# The fuzzers are now placed in build/out/markdown-it-py
-# To run the fuzz_markdown fuzzer:
-python3 infra/helper.py run_fuzzer markdown-it-py fuzz_markdown
-```
+## CI integration
+
+Fuzzing essentially runs forever, or until a crash is found, therefore it cannot be fully integrated into local continous integration testing.
+The workflow in `.github/workflows/fuzz.yml` though runs a brief fuzzing on code changed in a PR,
+which can be used to provide early warning on code changes.
+
+## Reproducing crash failures
 
-## Extending so fuzzers run on OSS-Fuzz
-The build script on the OSS-Fuzz repository for markdown-it-py fuzzers is
-here: https://github.com/google/oss-fuzz/blob/master/projects/markdown-it-py/build.sh
+If OSS-Fuzz (or the CI workflow) identifies a crash, it will produce a "minimized testcase" file
+(e.g. <https://oss-fuzz.com/testcase-detail/5424112454729728>).
+
+To reproduce this crash locally, the easiest way is to run the [tox](https://tox.wiki/) environment, provided in this repository, against the test file (see `tox.ini`):
+
+```
+tox -e fuzz path/to/testcase
+```
 
-Any file that matches `fuzz_*.py` in this repository will be build and run on
-OSS-Fuzz. Thus, to extend with a new fuzzer simply name it accordingly.
+This idempotently sets up a local python environment with markdown-it-py (local dev) and [Atheris](https://pypi.org/project/atheris/) installed,
+clones <https://github.com/google/oss-fuzz> into it,
+and builds the fuzzers.
+Then the testcase is run within this environment.
 
-## Reproducing issues
-In order to reproduce an issue reported by OSS-Fuzz, you need to:
-1) Download the `Minimized Testcase` (which is a file or raw bytes) from the
-detailed OSS-Fuzz reports. Example link: https://oss-fuzz.com/testcase-detail/5424112454729728
-2) Build the fuzzers as shown above
-3) Use the command:
+If you wish to simply run the full fuzzing process,
+you can activate this environment, then run e.g.:
 
 ```
-python3 infra/helper.py reproduce markdown-it-py {FUZZER_NAME} {PATH_TO_MINIMIZED_TESTCASE}
+python .tox/fuzz/oss-fuzz/infra/helper.py run_fuzzer markdown-it-py fuzz_markdown
 ```
 
 For a more thorough guide on reproducing, see: https://google.github.io/oss-fuzz/advanced-topics/reproducing/