tweak ext-fuzzer introduction

Author: Zac-HD

hypothesis-python/docs/how-to/external-fuzzers.rst

@@ -1,11 +1,14 @@
-Use an external fuzzer with Hypothesis
+Use Hypothesis with an external fuzzer
 ======================================
 
-.. seealso::
+We think property-based testing is great, but sometimes you might want to point a traditional fuzzer at your code, such as `python-afl <https://github.com/jwilk/python-afl>`__ or Google's :pypi:`atheris` (which instruments both Python and native extensions).
 
-    If you're looking to fuzz property-based tests, `HypoFuzz <https://hypofuzz.com/>`_ is a coverage-guided fuzzer built for Hypothesis.
+You might also want to use Hypothesis strategies to describe your input data, and our world-class shrinking and observability tools to wrangle the results.  That's exactly what this how-to guide is about!
 
-In a standard Hypothesis test run, Hypothesis is responsible for generating each test case. However, you might instead want to point a traditional fuzzer at your code, such as `python-afl <https://github.com/jwilk/python-afl>`__ or Google's :pypi:`atheris` (which instruments both Python and native extensions).
+.. note::
+
+    This page is about writing traditional 'fuzz harnesses' for an external fuzzer, using parts of Hypothesis.
+    If you already have Hypothesis tests and want to fuzz them, we strongly recommend the purpose-built `HypoFuzz <https://hypofuzz.com/>`_.
 
 In order to support this workflow, Hypothesis exposes the |fuzz_one_input| method. |fuzz_one_input| takes a bytestring, parses it into a test case, and executes the corresponding test once. This means you can treat each of your Hypothesis tests as a traditional fuzz target, by pointing the fuzzer at |fuzz_one_input|.
 
@@ -27,10 +30,10 @@ Note that |fuzz_one_input| bypasses the standard test lifecycle. In a standard t
 
 See the documentation of |fuzz_one_input| for details of how it interacts with other features of Hypothesis, such as |@settings|.
 
-Using Atheris with |fuzz_one_input|
------------------------------------
+Worked example: using Atheris
+-----------------------------
 
-Here is an example that uses the `Atheris <https://github.com/google/atheris>`__ coverage-guided fuzzer (which is built on top of `libFuzzer <https://llvm.org/docs/LibFuzzer.html>`_) with |fuzz_one_input|:
+Here is an example that uses |fuzz_one_input| with the `Atheris <https://github.com/google/atheris>`__ coverage-guided fuzzer (which is built on top of `libFuzzer <https://llvm.org/docs/LibFuzzer.html>`_):
 
 .. code-block:: python
 
@@ -41,28 +44,18 @@ Here is an example that uses the `Atheris <https://github.com/google/atheris>`__
 
     from hypothesis import given, strategies as st
 
-    json_strategy = st.deferred(lambda: st.none() | st.floats() | st.text() | lists)
-    lists = st.lists(json_strategy)
-
-    @given(json_strategy)
-    def test_json_dums_valid_json(value):
+    @given(
+        st.recursive(
+            st.none() | st.booleans() | st.integers() | st.floats() | st.text(),
+            lambda j: st.lists(j) | st.dictionaries(st.text(), j)
+        )
+    )
+    def test_json_dumps_valid_json(value):
         json.dumps(value)
 
-    atheris.Setup(sys.argv, test_json_dums_valid_json.hypothesis.fuzz_one_input)
+    atheris.Setup(sys.argv, test_json_dumps_valid_json.hypothesis.fuzz_one_input)
     atheris.Fuzz()
 
-You may also want to use ``atheris.instrument_all`` or ``atheris.instrument_imports`` in order to add coverage instrumentation to Atheris. For example, to instrument the ``json`` module for coverage:
-
-
-.. code-block:: python
-
-    ...
-
-    import atheris
-
-    with atheris.instrument_imports():
-        import json  # fmt: off
-
-    ...
+Generating valid JSON objects based only on Atheris' ``FuzzDataProvider`` interface would be considerably more difficult.
 
-See the `Atheris <https://github.com/google/atheris>`__ documentation for full details.
+You may also want to use ``atheris.instrument_all`` or ``atheris.instrument_imports`` in order to add coverage instrumentation to Atheris.  See the `Atheris <https://github.com/google/atheris>`__ documentation for full details.

hypothesis-python/src/hypothesis/core.py

@@ -1649,9 +1649,6 @@ def fuzz_one_input(
         """
         Run the test as a fuzz target, driven with the ``buffer`` of bytes.
 
-        Returns None if ``buffer`` was invalid for the strategy, canonical pruned
-        bytes if the buffer was valid, and leaves raised exceptions alone.
-
         Depending on the passed ``buffer`` one of three things will happen:
 
         * If the bytestring was invalid, for example because it was too short or was
@@ -1666,6 +1663,14 @@ def fuzz_one_input(
           minimize, and de-duplicate all the failures found via fuzzing is run
           your test suite!
 
+        To reduce the performance impact of database writes, |fuzz_one_input| only
+        records failing inputs which would be valid shrinks for a known failure -
+        meaning writes are somewhere between constant and log(N) rather than linear
+        in runtime.  However, this tracking only works within a persistent fuzzing
+        process; for forkserver fuzzers we recommend ``database=None`` for the main
+        run, and then replaying with a database enabled if you need to analyse
+        failures.
+
         Note that the interpretation of both input and output bytestrings is
         specific to the exact version of Hypothesis you are using and the strategies
         given to the test, just like the :ref:`database <database>` and