Document tests stanza

Signed-off-by: Rudi Grinberg <rudi.grinberg@gmail.com>

doc/dune-files.rst

@@ -240,6 +240,8 @@ Executables can also be linked as object or shared object files. See
         (section bin)
         (files (<name>.exe as <public-name>)))
 
+.. _shared-exe-fields:
+
 - ``(package <package>)`` if there is a ``(public_name ...)`` field, this
   specifies the package the executables are part of
 
@@ -548,6 +550,8 @@ The syntax is as follows:
 
 ``<name>`` is an alias name such as ``runtest``.
 
+.. _alias-fields:
+
 ``<deps-conf list>`` specifies the dependencies of the alias. See the
 `Dependency specification`_ section for more details.
 
@@ -698,6 +702,45 @@ With this dune file, running dune as follow will replace the
 
     $ dune build @runtest --auto-promote
 
+.. _tests-stanza:
+
+tests
+-----
+
+The ``tests`` stanza allows one to easily define multiple tests. For example we
+can define two tests at once with:
+
+.. code:: scheme
+
+   (tests
+    (names mytest expect_test)
+    <optional fields>)
+
+This will define an executable named ``mytest.exe`` that will be executed as
+part of the ``runtest`` alias. If the directory also contains an
+``expect_test.expected`` file, then ``expect_test`` will be used to define an
+expect test. That is, the test will be executed and its output will be compared
+to ``expect_test.expected``.
+
+The optional fields that are supported are a subset of the alias and executables
+fields. In particular, all fields except for ``public_names`` are supported from
+the `executables stanza <shared-exe-fields>`_. Alias fields apart from ``name``
+and ``action`` are allowed.
+
+test
+----
+
+The ``test`` stanza is the singular form of ``tests``. The only difference is
+that it's of the form:
+
+.. code:: scheme
+
+   (test
+    (name foo)
+    <optional fields>)
+
+where the ``name`` field is singular. The same optional fields are supported.
+
 .. _dune-env:
 
 env

doc/tests.rst

@@ -330,6 +330,14 @@ running your testsuite, simply add this to a jbuild file:
            ((name   runtest)
             (action (run ./tests.exe))))
 
+Hence to define an a test a pair of alias and executable stanzas are required.
+To simplify this common pattern, dune provides a :ref:`tests-stanza` stanza to
+define multiple tests and their aliases at once:
+
+.. code:: scheme
+
+   (tests (names test1 test2))
+
 Diffing the result
 ------------------
 
@@ -348,12 +356,21 @@ command. For instance let's consider this test:
            ((name runtest)
             (action (diff tests.expected test.output))))
 
-After having run ``tests.exe`` and dumping its output to
-``tests.output``, dune will compare the latter to
-``tests.expected``. In case of mismatch, dune will print a diff
-and then the ``dune promote`` command can be used to copy over the
-generated ``test.output`` file to ``tests.expected`` in the source
-tree. This provides a nice way of dealing with the usual *write code*,
+After having run ``tests.exe`` and dumping its output to ``tests.output``, dune
+will compare the latter to ``tests.expected``. In case of mismatch, dune will
+print a diff and then the ``dune promote`` command can be used to copy over the
+generated ``test.output`` file to ``tests.expected`` in the source tree.
+
+Alternatively, the :ref:`tests-stanza` also supports this style of tests.
+
+.. code:: scheme
+
+   (tests (names tests))
+
+Where dune expects a ``tests.expected`` file to exist to infer that this is an
+expect tests.
+
+This provides a nice way of dealing with the usual *write code*,
 *run*, *promote* cycle of testing. For instance:
 
 .. code:: bash