Doc: Document basic integration between gnattest and gnatfuzz

Although the features are not mature, document them so as not to
confuse users when seeing new command line options with no matching
documentation in the users' guide.

Author: leocreuse

doc/gnattest/gnattest_part.rst

@@ -926,10 +926,54 @@ The tool currently has the following limitations:
 
 .. _Automatic_testcase_generation:
 
-Automatically generating test cases (alpha)
--------------------------------------------
+Automatically generating test cases (experimental)
+--------------------------------------------------
 
-``gnattest`` provides a switch ``--gen-test-vectors`` that can be used to
+Please note that all the features described bellow are experimental, and the
+interface is subject to change.
+
+GNATtest has the capability to generate test inputs for subprograms under test.
+
+.. _Tgen_Env:
+
+Setting up the test generation runtime
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Generation of values for Ada cannot be fully done statically, as the bounds of
+some types may only be defined at runtime. As such, the test generation feature
+requires the compilation and installation of a runtime project.
+
+The sources for that project are located at
+``<GNATdas_install_dir/share/tgen/tgen_rts``.
+
+To build the runtime, simply copy the above directory to a location of you
+choice, build the project using ``gprbuild``, install it using ``gprinstall``
+and make it available to the tools by referencing it in the ``GPR_PROJECT_PATH``
+environment variable:
+
+.. code-block:: sh
+
+  # Clean previous source if present
+  rm -rf /tmp/tgen_rts_src
+
+  # Copy the sources
+  cp -r <GNATdas_install_dir>/share/tgen/tgen_rts /tmp/tgen_rts_src
+
+  # Build the project
+  cd /tmp/tgen_rts_src
+  gprbuild -P tgen_rts.gpr
+
+  # Install the project (removing the previous one if needed)
+  gprinstall --uninstall -P tgen_rts.gpr --prefix=/tmp/tgen_rts_install
+  gprinstall -p -P tgen_rts.gpr --prefix=/tmp/tgen_rts_install
+
+  # Make it available to other tools
+  export GPR_PROJECT_PATH=/tmp/tgen_rts_install/share/gpr:$GPR_PROJECT_PATH
+
+Generating test inputs
+^^^^^^^^^^^^^^^^^^^^^^
+
+``gnattest`` provides a ``--gen-test-vectors`` switch that can be used to
 automatically generate test cases for all of the supported subprogram profiles.
 The number of generated test cases can be configured through the
 ``--gen-test-num`` switch.
@@ -946,21 +990,39 @@ are true:
 5. Any of the subprogram's "in" or "out" mode parameters is a private type of
    a nested package.
 
-..
-   TODO: document a bit the value generation (mostly random, except for
-   unconstrained arrays and discriminated record).
+Input value generation currently follows a simple strategy for each input
+parameter of the subprogram under test. Parameters of scalar types, and scalar
+components of composite types have their values uniformly generated. For
+unconstrained array types, a length is randomly chosen between 0 and 10
+elements, then the low bound is randomly chosen and the high bound computed
+accordingly to those two first points.
+
+For record discriminants, different strategies are chosen depending on the use
+of the discriminant within the record: If the discriminant constraints a array
+component, then the array strategy described above is used. If the discriminant
+is used in a variant part, generation will be biased in order to generated all
+possible shapes of the record (i.e. explore all variants). Otherwise, these are
+generated as any other scalar component.
+
 
 The generated test cases are then stored in a ad-hoc (and yet to be specified)
-JSON format, in files under the <obj_dir>/gnattest/tests/JSON_Tests directory.
+JSON format, in files under the ``<obj_dir>/gnattest/tests/JSON_Tests`` directory.
 The generated JSON files are preserved through a ``gnattest`` rerun. The user is
 thus free to modify them, to e.g. fill in expected return values, though
 backward compatibility of the format is not guaranteed at this stage.
 
 ``gnattest`` also generates Ada files to actually execute the test cases. Each test vector
 has its own AUnit test case, and all test cases for a specific subprogram are all
 stored in a dedicated file, namely
-<unit_name>-test_data-test_<subp_name>_<subp_hash>.ad[bs]. The content of these
-files is not preserved through a ``gnattest`` rerun.
+``<unit_name>-test_data-test_<subp_name>_<subp_hash>.ad[bs]``, where
+``<unit_name>`` is the name of the unit in which the subprogram is declared,
+``<subp_name>`` is the name of the subprogram, and <subp_hash> is a hash based
+on the profile of the subprogram, in order to differentiate overloads.
+
+The content of these files are re-generated each time ``gnattest`` is invoked,
+independently of the presence of the ``--gen-test-vectors`` switch on the
+command line. It is thus not necessary to re-invoke ``gnattest`` with that
+switch more than once, unless the goal is to generate additional test inputs.
 
 ..
    TODO: document the --unparse switch

doc/integration/gs_menu.png

@@ -461,3 +461,72 @@ created in the same directory as each ``test_driver.gpr`` file. This file
 contains the name of the unit tested by the driver, and can be used to specify
 to |gcv| to only process the unit under test, by adding the switch
 :cmd-option:`[email protected]`.
+
+###########################################
+Using GNATtest with GNATfuzz (experimental)
+###########################################
+
+This section presents how a pre-existing GNATtest test harness can be used as
+a starting corpus for a GNATfuzz fuzzing campaign, and how inputs of interest
+found by GNATfuzz can be imported back into a GNATtest harness. These features
+are still experimental; the workflow and command line interface may change in
+the future.
+
+**************************
+Setting up the environment
+**************************
+
+To ensure the entire workflow functions properly, it's crucial to configure
+the various tools by setting specific environment variables.
+
+The first step is to setup the value generation runtime library. For detailed
+instructions on how to do so, see :ref:`Tgen_Env`.
+
+Then in order to activate the import and export of tests between GNATfuzz
+and GNATtest, the ``GNATFUZZ_TGEN`` environment variable must be set:
+
+.. code-block::bash
+   export GNATFUZZ_TGEN=1
+
+*******************************************
+Using GNATStudio to perform the integration
+*******************************************
+
+The simplest way to sequence the invocations of the two tools is to use the
+GNATstudio integration plugin.
+
+First, create a GNATtest harness project if it doesn't already exist, using the
+``Analyze -> GNATtest -> Generate harness project`` entries in the menu bar.
+Note that in the dialog box opening there is an option to generate tests inputs
+if needed.
+
+Then, exporting tests inputs from GNATtest to GNATfuzz and running a fuzzing
+campaign on a specific subprogram can be done by right-clicking on the
+declaration of the target subprogram, then selecting
+``GNATtest -> Start/Stop fuzzing subprogram``, as illustrated bellow.
+
+.. Image:: gs_menu.png
+
+This will first instrument sources and re-generate the GNATtest harness in order
+to be able to intercept the inputs passed to the subprogram, then run the test
+harness, dumping the inputs in a binary format that can be used by GNATfuzz.
+GNATstudio will then setup a fuzzing session on the subprogram, for which the
+parameters can be controlled through the various pop-up windows that will be
+displayed during the process.
+
+``gnatfuzz`` will periodically export newly found inputs in a human readable
+JSON format under ``<obj>/gnattest/test/JSON_Tests``, where ``<obj>`` designates
+the object directory of the project.
+
+The fuzzing session will stop once all the stopping criteria have been met. The
+fuzzing session can also be stopped early by right clicking on the subprogram
+declaration, then selecting ``GNATtest => Start/Stop fuzzing subprogram``.
+
+After the fuzzing sessions has ended, a new GNATtest harness will be
+regenerated, including the tests exported by the GNATfuzz session. These will
+appear in
+``<obj>/gnattest/tests/<unit_name>-test_data-test_<subp_name>_<subp_hash>.adb``,
+where ``<unit_name>`` is the name of the unit in which the subprogram is
+declared, ``<subp_name>`` is the name of the subprogram, and <subp_hash> is a
+hash based on the profile of the subprogram, in order to differentiate
+overloads.