[gnunet-scheme] 294/324: doc: Document tests in doc/scheme-gnunet.tm.

[gnunet]

This is an automated email from the git hooks/post-receive script.

maxime-devos pushed a commit to branch master
in repository gnunet-scheme.

commit 109212581b977cf7d55340bcab2bcb05700de1f3
Author: Maxime Devos <maximedevos@telenet.be>
AuthorDate: Mon Sep 13 21:43:23 2021 +0200

    doc: Document tests in doc/scheme-gnunet.tm.
    
    * README.org (Tests): Move to ...
    * doc/scheme-gnunet.tm (Writing tests): ... here and rewrite a little.
---
 README.org           | 21 ---------------------
 doc/scheme-gnunet.tm | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 21 deletions(-)

diff --git a/README.org b/README.org
index c09a091..4d2d3cb 100644
--- a/README.org
+++ b/README.org
@@ -101,27 +101,6 @@ to doc/scheme-gnunet.tm.
    and ‘no-index’ should be ‘passed’ using SRFI-39 parameters,
    and not with positional or keyword arguments,
    as they are just passed through unchanged most of the time.
-** Tests
-   Read --> [[https://sqlite.org/testing.html][How SQLite Is Tested]] 
(accessed: 2021)
-
-   This GNUnet implementation isn't quite that well-tested,
-   and most likely won't be for the foreseeable future.  However,
-   when defining new code, try to define the following kind of
-   tests where reasonable (non-exhaustive);
-
-   + verify (iso-)morphisms and similar properties are upheld (e.g.
-     using guile-quickcheck for generating test cases).  E.g. if there
-     is a conversion function f : X -> Y and g : Y -> X, verify
-     (compose f g) = id = (compose g f).  Verify morphisms like
-     (length (append x y)) = length (x) + length (y).
-   + Run mutation tests!  That is, replace < with <=, 0 by 1, a variable
-     reference ‘i’ by a variable reference ‘j’, swap destination and source
-     arguments ... and verify whether the tests catch these little mutations!
-   + Verify argument checking!
-     (basic non-dependent type checking, in-bounds, right capabilities ...,
-     appropriate exception).   An &assertion is usually fine, though
-     occassionally a more informative condition may be in-place.
-
 * Wishlist
   + Schemification
 
diff --git a/doc/scheme-gnunet.tm b/doc/scheme-gnunet.tm
index 1e7bbae..3771c64 100644
--- a/doc/scheme-gnunet.tm
+++ b/doc/scheme-gnunet.tm
@@ -86,6 +86,38 @@
     1917 25EE
   </shell-code>
 
+  <section|Writing tests>
+
+  \<#2018\><hlink|How SQLite Is 
Tested|https://sqlite.org/testing.html>\<#2019\>
+  is a recommended read.<space|1em>Scheme-GNUnet isn't that well-tested but
+  still aims for being free of bugs and having many tests to prevents bugs
+  from being introduced.<space|1em>When adding new code, consider writing
+  test cases.<space|1em>Some things that can be tested and few methods for
+  testing things:
+
+  <\itemize>
+    <item>Run mutation tests.<space|1em>That is, replace in the source code
+    <scm|\<less\>> with <scm|\<less\>=>, <scm|0> with <scm|1>, a variable
+    reference <scm|i> with a variable reference <scm|j>, swap destination and
+    source arguments <text-dots> and verify whether the tests detect these
+    little mutations.
+
+    <item>Be exhaustive.<space|1em>If a procedure handles both foos and bars,
+    write test cases that pass the procedure a foo and test cases that pass
+    the procedure a bar.<space|1em>Sometimes Guile-QuickCheck can help with
+    generating many test cases if the input has a regular structure yet many
+    edge cases, see e.g. <verbatim|tests/cmsg.scm>.
+
+    <item>Verify exception mechanisms!<space|1em>If a procedure is expected
+    to handle I/O errors, simulate I/O errors and end-of-files in all the
+    wrong places.<space|1em>If the procedure can raise exceptions, make sure
+    these exceptions are raised when necessary.
+  </itemize>
+
+  Tests are added in the directory <scm|tests> and to the variable
+  <verbatim|SCM_TESTS> in <verbatim|Makefile.am> and use <scm|srfi
+  :64>.<space|1em>To run the test suite, run <verbatim|make check>.
+
   <chapter|Application guide>
 
   TODO<chapter|Programming guide>

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.