pw_fuzzer/guides/fuzztest.rst - pigweed/pigweed - Git at Google

 .. _module-pw_fuzzer-guides-using_fuzztest:

 ========================================
 pw_fuzzer: Adding Fuzzers Using FuzzTest
 ========================================
 .. pigweed-module-subpage::
    :name: pw_fuzzer

 .. note::

   `FuzzTest`_ is currently only supported on Linux and MacOS using Clang.

 .. _module-pw_fuzzer-guides-using_fuzztest-toolchain:

 ----------------------------------------
 Step 0: Set up FuzzTest for your project
 ----------------------------------------
 .. note::

    This workflow only needs to be done once for a project.

 FuzzTest and its dependencies are not included in Pigweed and need to be added.

 See the following:

 * :ref:`module-pw_third_party_abseil_cpp-using_upstream`
 * :ref:`module-pw_third_party_fuzztest-using_upstream`
 * :ref:`module-pw_third_party_googletest-using_upstream`
 * :ref:`module-pw_third_party_re2-using_upstream`

 .. tab-set::

    .. tab-item:: GN
       :sync: gn

       You may not want to use upstream GoogleTest all the time. For example, it
       may not be supported on your target device. In this case, you can limit it
       to a specific toolchain used for fuzzing. For example:

       .. code-block::

          import("$dir_pw_toolchain/host/target_toolchains.gni")

          my_toolchains = {
            ...
            clang_fuzz = {
              name = "my_clang_fuzz"
              forward_variables_from(pw_toolchain_host.clang_fuzz, "*", ["name"])
              pw_unit_test_MAIN = "$dir_pw_fuzzer:fuzztest_main"
              pw_unit_test_BACKEND = "$dir_pw_fuzzer:gtest"
            }
            ...
          }

    .. tab-item:: CMake
       :sync: cmake

       FuzzTest is enabled by setting several CMake variables. The easiest way to
       set these is to extend your ``toolchain.cmake`` file.

       For example:

       .. code-block::

          include(my_project_toolchain.cmake)

          set(dir_pw_third_party_fuzztest
              "path/to/fuzztest"
            CACHE STRING "" FORCE
          )
          set(dir_pw_third_party_googletest
              "path/to/googletest"
            CACHE STRING "" FORCE
          )
          set(pw_unit_test_BACKEND
              "pw_third_party.fuzztest"
            CACHE STRING "" FORCE
          )

    .. tab-item:: Bazel
       :sync: bazel

       FuzzTest provides a build configuration that can be imported into your
       ``.bazelrc`` file. Add the following:

       .. code-block::

          # Include FuzzTest build configurations.
          try-import %workspace%/third_party/fuzztest/fuzztest.bazelrc
          build:fuzztest --@pigweed//targets:fuzztest_config=//pw_fuzzer:fuzztest

 ----------------------------------------
 Step 1: Write a unit test for the target
 ----------------------------------------

 As noted previously, the very first step is to identify one or more target
 behavior that would benefit from testing. See `FuzzTest Use Cases`_ for more
 details on how to identify this code.

 Once identified, it is useful to start from a unit test. You may already have a
 unit test writtern, but if not it is likely still be helpful to write one first.
 Many developers are more familiar with writing unit tests, and there are
 detailed guides available. See for example the `GoogleTest documentation`_.

 This guide will use code from ``//pw_fuzzer/examples/fuzztest/``. This code
 includes the following object as an example of code that would benefit from
 fuzzing for undefined behavior and from roundtrip fuzzing.

 .. note::

    To keep the example simple, this code uses the standard library. As a result,
    this code may not work with certain devices.

 .. literalinclude:: ../examples/fuzztest/metrics.h
    :language: cpp
    :linenos:
    :start-after: [pwfuzzer_examples_fuzztest-metrics_h]
    :end-before: [pwfuzzer_examples_fuzztest-metrics_h]

 Unit tests for this class might attempt to deserialize previously serialized
 objects and to deserialize invalid data:

 .. literalinclude:: ../examples/fuzztest/metrics_unittest.cc
    :language: cpp
    :linenos:
    :start-after: [pwfuzzer_examples_fuzztest-metrics_unittest]
    :end-before: [pwfuzzer_examples_fuzztest-metrics_unittest]

 --------------------------------------------
 Step 2: Convert your unit test to a function
 --------------------------------------------

 Examine your unit tests and identify any places you have fixed values that could
 vary. Turn your unit test into a function that takes those values as parameters.
 Since fuzzing may not occur on all targets, you should preserve your unit test
 by calling the new function with the previously fixed values.

 .. literalinclude:: ../examples/fuzztest/metrics_fuzztest.cc
    :language: cpp
    :linenos:
    :start-after: [pwfuzzer_examples_fuzztest-metrics_fuzztest1]
    :end-before: [pwfuzzer_examples_fuzztest-metrics_fuzztest1]

 .. literalinclude:: ../examples/fuzztest/metrics_fuzztest.cc
    :language: cpp
    :linenos:
    :start-after: [pwfuzzer_examples_fuzztest-metrics_fuzztest3]
    :end-before: [pwfuzzer_examples_fuzztest-metrics_fuzztest3]

 Note that in ``ArbitrarySerializeAndDeserialize`` we no longer assume the
 marshalling will always be successful, and exit early if it is not. You may need
 to make similar modifications to your unit tests if constraints on parameters
 are not expressed by `domains`__ as described below.

 .. __: `FuzzTest Domain Reference`_

 --------------------------------------------
 Step 3: Add a FUZZ_TEST macro invocation
 --------------------------------------------

 Now, include ``"fuzztest/fuzztest.h"`` and pass the test suite name and your
 function name to the ``FUZZ_TEST`` macro. Call ``WithDomains`` on the returned
 object to specify the input domain for each parameter of the function. For
 example:

 .. literalinclude:: ../examples/fuzztest/metrics_fuzztest.cc
    :language: cpp
    :linenos:
    :start-after: [pwfuzzer_examples_fuzztest-metrics_fuzztest2]
    :end-before: [pwfuzzer_examples_fuzztest-metrics_fuzztest2]

 .. literalinclude:: ../examples/fuzztest/metrics_fuzztest.cc
    :language: cpp
    :linenos:
    :start-after: [pwfuzzer_examples_fuzztest-metrics_fuzztest4]
    :end-before: [pwfuzzer_examples_fuzztest-metrics_fuzztest4]

 You may know of specific values that are "interesting", i.e. that represent
 boundary conditions, involve, special handling, etc. To guide the fuzzer towards
 these code paths, you can include them as `seeds`_. However, as noted in
 the comments of the examples, it is recommended to include a unit test with the
 original parameters to ensure the code is tested on target devices.

 FuzzTest provides more detailed documentation on these topics. For example:

 * Refer to `The FUZZ_TEST Macro`_ reference for more details on how to use this
   macro.

 * Refer to the `FuzzTest Domain Reference`_ for details on all the different
   types of domains supported by FuzzTest and how they can be combined.

 * Refer to the `Test Fixtures`_ reference for how to create fuzz tests from unit
   tests that use GoogleTest fixtures.

 ------------------------------------
 Step 4: Add the fuzzer to your build
 ------------------------------------
 Next, indicate that the unit test includes one or more fuzz tests.

 .. tab-set::

    .. tab-item:: GN
       :sync: gn

       The ``pw_fuzz_test`` template can be used to add the necessary FuzzTest
       dependency and generate test metadata.

       For example, consider the following ``BUILD.gn``:

       .. literalinclude:: ../examples/fuzztest/BUILD.gn
          :linenos:
          :start-after: [pwfuzzer_examples_fuzztest-gn]
          :end-before: [pwfuzzer_examples_fuzztest-gn]

    .. tab-item:: CMake
       :sync: cmake

       Unit tests can support fuzz tests by simply adding a dependency on
       FuzzTest.

       For example, consider the following ``CMakeLists.txt``:

       .. literalinclude:: ../examples/fuzztest/CMakeLists.txt
          :linenos:
          :start-after: [pwfuzzer_examples_fuzztest-cmake]
          :end-before: [pwfuzzer_examples_fuzztest-cmake]

    .. tab-item:: Bazel
       :sync: bazel

       Unit tests can support fuzz tests by simply adding a dependency on
       FuzzTest.

       For example, consider the following ``BUILD.bazel``:

       .. literalinclude:: ../examples/fuzztest/BUILD.bazel
          :linenos:
          :start-after: [pwfuzzer_examples_fuzztest-bazel]
          :end-before: [pwfuzzer_examples_fuzztest-bazel]

 ------------------------
 Step 5: Build the fuzzer
 ------------------------
 .. tab-set::

    .. tab-item:: GN
       :sync: gn

       Build using ``ninja`` on a target that includes your fuzzer with a
       :ref:`fuzzing toolchain<module-pw_fuzzer-guides-using_fuzztest-toolchain>`.

       Pigweed includes a ``//:fuzzers`` target that builds all tests, including
       those with fuzzers, using a fuzzing toolchain. You may wish to add a
       similar top-level to your project. For example:

       .. code-block::

          group("fuzzers") {
            deps = [ ":pw_module_tests.run($dir_pigweed/targets/host:host_clang_fuzz)" ]
          }

    .. tab-item:: CMake
       :sync: cmake

       Build using ``cmake`` with the FuzzTest and GoogleTest variables set. For
       example:

       .. code-block::

          cmake ... \
            -Ddir_pw_third_party_fuzztest=path/to/fuzztest \
            -Ddir_pw_third_party_googletest=path/to/googletest \
            -Dpw_unit_test_BACKEND=pw_third_party.fuzztest


    .. tab-item:: Bazel
       :sync: bazel

       By default, ``bazel`` will simply omit the fuzz tests and build unit
       tests. To build these tests as fuzz tests, specify the ``fuzztest``
       config. For example:

       .. code-block:: sh

          bazel build //... --config=fuzztest

 ----------------------------------
 Step 6: Running the fuzzer locally
 ----------------------------------
 .. TODO: b/281138993 - Add tooling to make it easier to find and run fuzzers.

 .. tab-set::

    .. tab-item:: GN
       :sync: gn

       When building. Most toolchains will simply omit the fuzz tests and build
       and run unit tests. A
       :ref:`fuzzing toolchain<module-pw_fuzzer-guides-using_fuzztest-toolchain>`
       will include the fuzzers, but only run them for a limited time. This makes
       them suitable for automated testing as in CQ.

       If you used the top-level ``//:fuzzers`` described in the previous
       section, you can find available fuzzers using the generated JSON test
       metadata file:

       .. code-block:: sh

          jq '.[] | select(contains({tags: ["fuzztest"]}))' \
            out/host_clang_fuzz/obj/pw_module_tests.testinfo.json

       To run a fuzz with different options, you can pass additional flags to the
       fuzzer binary. This binary will be in a subdirectory related to the
       toolchain. For example:

       .. code-block:: sh

          out/host_clang_fuzz/obj/my_module/test/metrics_test \
            --fuzz=MetricsTest.Roundtrip

       Additional `sanitizer flags`_ may be passed uisng environment variables.

    .. tab-item:: CMake
       :sync: cmake

       When built with FuzzTest and GoogleTest, the fuzzer binaries can be run
       directly from the CMake build directory. By default, the fuzzers will only
       run for a limited time. This makes them suitable for automated testing as
       in CQ. To run a fuzz with different options, you can pass additional flags
       to the fuzzer binary.

       For example:

       .. code-block:: sh

          build/my_module/metrics_test --fuzz=MetricsTest.Roundtrip

    .. tab-item:: Bazel
       :sync: bazel

       By default, ``bazel`` will simply omit the fuzz tests and build and run
       unit tests. To build these tests as fuzz tests, specify the "fuzztest"
       config. For example:

       .. code-block:: sh

          bazel test //... --config=fuzztest

       This will build the tests as fuzz tests, but only run them for a limited
       time. This makes them suitable for automated testing as in CQ.

       To run a fuzz with different options, you can use ``run`` and pass
       additional flags to the fuzzer binary. For example:

       .. code-block:: sh

          bazel run //my_module:metrics_test --config=fuzztest \
            --fuzz=MetricsTest.Roundtrip

 Running the fuzzer should produce output similar to the following:

 .. code-block::

    [.] Sanitizer coverage enabled. Counter map size: 21290, Cmp map size: 262144
    Note: Google Test filter = MetricsTest.Roundtrip
    [==========] Running 1 test from 1 test suite.
    [----------] Global test environment set-up.
    [----------] 1 test from MetricsTest
    [ RUN      ] MetricsTest.Roundtrip
    [*] Corpus size:     1 | Edges covered:    131 | Fuzzing time:    504.798us | Total runs:  1.00e+00 | Runs/secs:     1
    [*] Corpus size:     2 | Edges covered:    133 | Fuzzing time:    934.176us | Total runs:  3.00e+00 | Runs/secs:     3
    [*] Corpus size:     3 | Edges covered:    134 | Fuzzing time:   2.384383ms | Total runs:  5.30e+01 | Runs/secs:    53
    [*] Corpus size:     4 | Edges covered:    137 | Fuzzing time:   2.732274ms | Total runs:  5.40e+01 | Runs/secs:    54
    [*] Corpus size:     5 | Edges covered:    137 | Fuzzing time:   7.275553ms | Total runs:  2.48e+02 | Runs/secs:   248

 .. TODO: b/282560789 - Add guides/improve_fuzzers.rst
 .. TODO: b/281139237 - Add guides/continuous_fuzzing.rst
 .. ----------
 .. Next steps
 .. ----------
 .. Once you have a working fuzzer, the next steps are to:

 .. * `Run it continuously on a fuzzing infrastructure <continuous_fuzzing>`_.
 .. * `Measure its code coverage and improve it <improve_fuzzers>`_.

 .. _FuzzTest: https://github.com/google/fuzztest
 .. _FuzzTest Domain Reference: https://github.com/google/fuzztest/blob/main/doc/domains-reference.md
 .. _FuzzTest Use Cases: https://github.com/google/fuzztest/blob/main/doc/use-cases.md
 .. _GoogleTest documentation: https://google.github.io/googletest/
 .. _Test Fixtures: https://github.com/google/fuzztest/blob/main/doc/fixtures.md
 .. _The FUZZ_TEST Macro: https://github.com/google/fuzztest/blob/main/doc/fuzz-test-macro.md
 .. _sanitizer flags: https://github.com/google/sanitizers/wiki/SanitizerCommonFlags
 .. _seeds: https://github.com/google/fuzztest/blob/main/doc/fuzz-test-macro.md#initial-seeds
	.. _module-pw_fuzzer-guides-using_fuzztest:

	========================================
	pw_fuzzer: Adding Fuzzers Using FuzzTest
	========================================
	.. pigweed-module-subpage::
	:name: pw_fuzzer

	.. note::

	`FuzzTest`_ is currently only supported on Linux and MacOS using Clang.

	.. _module-pw_fuzzer-guides-using_fuzztest-toolchain:

	----------------------------------------
	Step 0: Set up FuzzTest for your project
	----------------------------------------
	.. note::

	This workflow only needs to be done once for a project.

	FuzzTest and its dependencies are not included in Pigweed and need to be added.

	See the following:

	* :ref:`module-pw_third_party_abseil_cpp-using_upstream`
	* :ref:`module-pw_third_party_fuzztest-using_upstream`
	* :ref:`module-pw_third_party_googletest-using_upstream`
	* :ref:`module-pw_third_party_re2-using_upstream`

	.. tab-set::

	.. tab-item:: GN
	:sync: gn

	You may not want to use upstream GoogleTest all the time. For example, it
	may not be supported on your target device. In this case, you can limit it
	to a specific toolchain used for fuzzing. For example:

	.. code-block::

	import("$dir_pw_toolchain/host/target_toolchains.gni")

	my_toolchains = {
	...
	clang_fuzz = {
	name = "my_clang_fuzz"
	forward_variables_from(pw_toolchain_host.clang_fuzz, "*", ["name"])
	pw_unit_test_MAIN = "$dir_pw_fuzzer:fuzztest_main"
	pw_unit_test_BACKEND = "$dir_pw_fuzzer:gtest"
	}
	...
	}

	.. tab-item:: CMake
	:sync: cmake

	FuzzTest is enabled by setting several CMake variables. The easiest way to
	set these is to extend your ``toolchain.cmake`` file.

	For example:

	.. code-block::

	include(my_project_toolchain.cmake)

	set(dir_pw_third_party_fuzztest
	"path/to/fuzztest"
	CACHE STRING "" FORCE
	)
	set(dir_pw_third_party_googletest
	"path/to/googletest"
	CACHE STRING "" FORCE
	)
	set(pw_unit_test_BACKEND
	"pw_third_party.fuzztest"
	CACHE STRING "" FORCE
	)

	.. tab-item:: Bazel
	:sync: bazel

	FuzzTest provides a build configuration that can be imported into your
	``.bazelrc`` file. Add the following:

	.. code-block::

	# Include FuzzTest build configurations.
	try-import %workspace%/third_party/fuzztest/fuzztest.bazelrc
	build:fuzztest --@pigweed//targets:fuzztest_config=//pw_fuzzer:fuzztest

	----------------------------------------
	Step 1: Write a unit test for the target
	----------------------------------------

	As noted previously, the very first step is to identify one or more target
	behavior that would benefit from testing. See `FuzzTest Use Cases`_ for more
	details on how to identify this code.

	Once identified, it is useful to start from a unit test. You may already have a
	unit test writtern, but if not it is likely still be helpful to write one first.
	Many developers are more familiar with writing unit tests, and there are
	detailed guides available. See for example the `GoogleTest documentation`_.

	This guide will use code from ``//pw_fuzzer/examples/fuzztest/``. This code
	includes the following object as an example of code that would benefit from
	fuzzing for undefined behavior and from roundtrip fuzzing.

	.. note::

	To keep the example simple, this code uses the standard library. As a result,
	this code may not work with certain devices.

	.. literalinclude:: ../examples/fuzztest/metrics.h
	:language: cpp
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-metrics_h]
	:end-before: [pwfuzzer_examples_fuzztest-metrics_h]

	Unit tests for this class might attempt to deserialize previously serialized
	objects and to deserialize invalid data:

	.. literalinclude:: ../examples/fuzztest/metrics_unittest.cc
	:language: cpp
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-metrics_unittest]
	:end-before: [pwfuzzer_examples_fuzztest-metrics_unittest]

	--------------------------------------------
	Step 2: Convert your unit test to a function
	--------------------------------------------

	Examine your unit tests and identify any places you have fixed values that could
	vary. Turn your unit test into a function that takes those values as parameters.
	Since fuzzing may not occur on all targets, you should preserve your unit test
	by calling the new function with the previously fixed values.

	.. literalinclude:: ../examples/fuzztest/metrics_fuzztest.cc
	:language: cpp
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-metrics_fuzztest1]
	:end-before: [pwfuzzer_examples_fuzztest-metrics_fuzztest1]

	.. literalinclude:: ../examples/fuzztest/metrics_fuzztest.cc
	:language: cpp
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-metrics_fuzztest3]
	:end-before: [pwfuzzer_examples_fuzztest-metrics_fuzztest3]

	Note that in ``ArbitrarySerializeAndDeserialize`` we no longer assume the
	marshalling will always be successful, and exit early if it is not. You may need
	to make similar modifications to your unit tests if constraints on parameters
	are not expressed by `domains`__ as described below.

	.. __: `FuzzTest Domain Reference`_

	--------------------------------------------
	Step 3: Add a FUZZ_TEST macro invocation
	--------------------------------------------

	Now, include ``"fuzztest/fuzztest.h"`` and pass the test suite name and your
	function name to the ``FUZZ_TEST`` macro. Call ``WithDomains`` on the returned
	object to specify the input domain for each parameter of the function. For
	example:

	.. literalinclude:: ../examples/fuzztest/metrics_fuzztest.cc
	:language: cpp
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-metrics_fuzztest2]
	:end-before: [pwfuzzer_examples_fuzztest-metrics_fuzztest2]

	.. literalinclude:: ../examples/fuzztest/metrics_fuzztest.cc
	:language: cpp
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-metrics_fuzztest4]
	:end-before: [pwfuzzer_examples_fuzztest-metrics_fuzztest4]

	You may know of specific values that are "interesting", i.e. that represent
	boundary conditions, involve, special handling, etc. To guide the fuzzer towards
	these code paths, you can include them as `seeds`_. However, as noted in
	the comments of the examples, it is recommended to include a unit test with the
	original parameters to ensure the code is tested on target devices.

	FuzzTest provides more detailed documentation on these topics. For example:

	* Refer to `The FUZZ_TEST Macro`_ reference for more details on how to use this
	macro.

	* Refer to the `FuzzTest Domain Reference`_ for details on all the different
	types of domains supported by FuzzTest and how they can be combined.

	* Refer to the `Test Fixtures`_ reference for how to create fuzz tests from unit
	tests that use GoogleTest fixtures.

	------------------------------------
	Step 4: Add the fuzzer to your build
	------------------------------------
	Next, indicate that the unit test includes one or more fuzz tests.

	.. tab-set::

	.. tab-item:: GN
	:sync: gn

	The ``pw_fuzz_test`` template can be used to add the necessary FuzzTest
	dependency and generate test metadata.

	For example, consider the following ``BUILD.gn``:

	.. literalinclude:: ../examples/fuzztest/BUILD.gn
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-gn]
	:end-before: [pwfuzzer_examples_fuzztest-gn]

	.. tab-item:: CMake
	:sync: cmake

	Unit tests can support fuzz tests by simply adding a dependency on
	FuzzTest.

	For example, consider the following ``CMakeLists.txt``:

	.. literalinclude:: ../examples/fuzztest/CMakeLists.txt
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-cmake]
	:end-before: [pwfuzzer_examples_fuzztest-cmake]

	.. tab-item:: Bazel
	:sync: bazel

	Unit tests can support fuzz tests by simply adding a dependency on
	FuzzTest.

	For example, consider the following ``BUILD.bazel``:

	.. literalinclude:: ../examples/fuzztest/BUILD.bazel
	:linenos:
	:start-after: [pwfuzzer_examples_fuzztest-bazel]
	:end-before: [pwfuzzer_examples_fuzztest-bazel]

	------------------------
	Step 5: Build the fuzzer
	------------------------
	.. tab-set::

	.. tab-item:: GN
	:sync: gn

	Build using ``ninja`` on a target that includes your fuzzer with a
	:ref:`fuzzing toolchain<module-pw_fuzzer-guides-using_fuzztest-toolchain>`.

	Pigweed includes a ``//:fuzzers`` target that builds all tests, including
	those with fuzzers, using a fuzzing toolchain. You may wish to add a
	similar top-level to your project. For example:

	.. code-block::

	group("fuzzers") {
	deps = [ ":pw_module_tests.run($dir_pigweed/targets/host:host_clang_fuzz)" ]
	}

	.. tab-item:: CMake
	:sync: cmake

	Build using ``cmake`` with the FuzzTest and GoogleTest variables set. For
	example:

	.. code-block::

	cmake ... \
	-Ddir_pw_third_party_fuzztest=path/to/fuzztest \
	-Ddir_pw_third_party_googletest=path/to/googletest \
	-Dpw_unit_test_BACKEND=pw_third_party.fuzztest


	.. tab-item:: Bazel
	:sync: bazel

	By default, ``bazel`` will simply omit the fuzz tests and build unit
	tests. To build these tests as fuzz tests, specify the ``fuzztest``
	config. For example:

	.. code-block:: sh

	bazel build //... --config=fuzztest

	----------------------------------
	Step 6: Running the fuzzer locally
	----------------------------------
	.. TODO: b/281138993 - Add tooling to make it easier to find and run fuzzers.

	.. tab-set::

	.. tab-item:: GN
	:sync: gn

	When building. Most toolchains will simply omit the fuzz tests and build
	and run unit tests. A
	:ref:`fuzzing toolchain<module-pw_fuzzer-guides-using_fuzztest-toolchain>`
	will include the fuzzers, but only run them for a limited time. This makes
	them suitable for automated testing as in CQ.

	If you used the top-level ``//:fuzzers`` described in the previous
	section, you can find available fuzzers using the generated JSON test
	metadata file:

	.. code-block:: sh

	jq '.[] \| select(contains({tags: ["fuzztest"]}))' \
	out/host_clang_fuzz/obj/pw_module_tests.testinfo.json

	To run a fuzz with different options, you can pass additional flags to the
	fuzzer binary. This binary will be in a subdirectory related to the
	toolchain. For example:

	.. code-block:: sh

	out/host_clang_fuzz/obj/my_module/test/metrics_test \
	--fuzz=MetricsTest.Roundtrip

	Additional `sanitizer flags`_ may be passed uisng environment variables.

	.. tab-item:: CMake
	:sync: cmake

	When built with FuzzTest and GoogleTest, the fuzzer binaries can be run
	directly from the CMake build directory. By default, the fuzzers will only
	run for a limited time. This makes them suitable for automated testing as
	in CQ. To run a fuzz with different options, you can pass additional flags
	to the fuzzer binary.

	For example:

	.. code-block:: sh

	build/my_module/metrics_test --fuzz=MetricsTest.Roundtrip

	.. tab-item:: Bazel
	:sync: bazel

	By default, ``bazel`` will simply omit the fuzz tests and build and run
	unit tests. To build these tests as fuzz tests, specify the "fuzztest"
	config. For example:

	.. code-block:: sh

	bazel test //... --config=fuzztest

	This will build the tests as fuzz tests, but only run them for a limited
	time. This makes them suitable for automated testing as in CQ.

	To run a fuzz with different options, you can use ``run`` and pass
	additional flags to the fuzzer binary. For example:

	.. code-block:: sh

	bazel run //my_module:metrics_test --config=fuzztest \
	--fuzz=MetricsTest.Roundtrip

	Running the fuzzer should produce output similar to the following:

	.. code-block::

	[.] Sanitizer coverage enabled. Counter map size: 21290, Cmp map size: 262144
	Note: Google Test filter = MetricsTest.Roundtrip
	[==========] Running 1 test from 1 test suite.
	[----------] Global test environment set-up.
	[----------] 1 test from MetricsTest
	[ RUN ] MetricsTest.Roundtrip
	[*] Corpus size: 1 \| Edges covered: 131 \| Fuzzing time: 504.798us \| Total runs: 1.00e+00 \| Runs/secs: 1
	[*] Corpus size: 2 \| Edges covered: 133 \| Fuzzing time: 934.176us \| Total runs: 3.00e+00 \| Runs/secs: 3
	[*] Corpus size: 3 \| Edges covered: 134 \| Fuzzing time: 2.384383ms \| Total runs: 5.30e+01 \| Runs/secs: 53
	[*] Corpus size: 4 \| Edges covered: 137 \| Fuzzing time: 2.732274ms \| Total runs: 5.40e+01 \| Runs/secs: 54
	[*] Corpus size: 5 \| Edges covered: 137 \| Fuzzing time: 7.275553ms \| Total runs: 2.48e+02 \| Runs/secs: 248

	.. TODO: b/282560789 - Add guides/improve_fuzzers.rst
	.. TODO: b/281139237 - Add guides/continuous_fuzzing.rst
	.. ----------
	.. Next steps
	.. ----------
	.. Once you have a working fuzzer, the next steps are to:

	.. * `Run it continuously on a fuzzing infrastructure <continuous_fuzzing>`_.
	.. * `Measure its code coverage and improve it <improve_fuzzers>`_.

	.. _FuzzTest: https://github.com/google/fuzztest
	.. _FuzzTest Domain Reference: https://github.com/google/fuzztest/blob/main/doc/domains-reference.md
	.. _FuzzTest Use Cases: https://github.com/google/fuzztest/blob/main/doc/use-cases.md
	.. _GoogleTest documentation: https://google.github.io/googletest/
	.. _Test Fixtures: https://github.com/google/fuzztest/blob/main/doc/fixtures.md
	.. _The FUZZ_TEST Macro: https://github.com/google/fuzztest/blob/main/doc/fuzz-test-macro.md
	.. _sanitizer flags: https://github.com/google/sanitizers/wiki/SanitizerCommonFlags
	.. _seeds: https://github.com/google/fuzztest/blob/main/doc/fuzz-test-macro.md#initial-seeds