Adding some hints about testing.

1 files changed, 81 insertions, 0 deletions

diff --git a/doc/onboarding.texi b/doc/onboarding.texi
index 5bd29d8..bc9c236 100644
--- a/doc/onboarding.texi
+++ b/doc/onboarding.texi
@@ -53,6 +53,7 @@ Texts.  A copy of the license is included in the section entitled
 * Taler.net::                           Sysadmins notes for server at taler.net
 * Standalone deployment::               Deploy Taler in your homepage
 * Deployment on demo.taler.net::        Deploy Taler in a "blue/green" fashion
+* Testing components::                  How to make and run tests.
 * Releases::                            Releases patterns
 @end menu
 
@@ -579,6 +580,86 @@ $ taler-deployment-start
 
 Now the symlink can be updated.
 
+@node Testing components
+@chapter Testing components
+
+@c CMDs
+@c Traits
+@c Twister setup
+
+This chapter is a VERY ABSTRACT description of how testing
+is implemented in Taler, and in NO WAY wants to substitute
+the reading of the actual source code by the user.
+
+In Taler, a test case is a array of @code{struct TALER_TESTING_Command},
+informally referred to as @code{CMD}, that is iteratively executed by
+the testing interpreter.  This latter is transparently initiated
+by the testing library.
+
+However, the developer does not have to defined CMDs manually,
+but rather call the proper constructor provided by the library.
+For example, if a CMD is supposed to test feature @code{x},
+then the library would provide the @code{TALER_TESTING_cmd_x ()}
+constructor for it.  Obviously, each constructor has its own
+particular arguments that make sense to test @code{x}, and all
+constructor are thoroughly commented within the source code.
+
+Internally, each CMD has two methods: @code{run ()} and @code{cleanup ()}.
+The former contains the main logic to test feature @code{x},
+whereas the latter cleans the memory up after execution.
+
+In a test life, each CMD needs some internal state, made by
+values it keeps in memory. Often, the test has to @emph{share}
+those values with other CMDs: for example, CMD1 may create some
+key material and CMD2 needs this key material to encrypt data.
+
+The offering of internal values from CMD1 to CMD2 is made
+by @emph{traits}.  A trait is a @code{struct TALER_TESTING_Trait},
+and each CMD contains a array of traits, that it offers
+via the public trait interface to other commands.  The
+definition and filling of such array happens transparently
+to the test developer.
+
+For example, the following example shows how CMD2 takes
+an amount object offered by CMD1 via the trait interface.
+
+Note: the main interpreter and the most part of CMDs and traits
+are hosted inside the exchange codebase, but nothing prevents
+the developer from implementing new CMDs and traits within
+other codebases.
+
+@example
+/* Withouth loss of generality, let's consider the
+ * following logic to exist inside the run() method of CMD1 */
+
+..
+
+struct TALER_Amount *a;
+/**
+ * the second argument (0) points to the first amount object offered,
+ * in case multiple are available.
+ */
+if (GNUNET_OK != TALER_TESTING_get_trait_amount_obj (cmd2, 0, &a))
+  return GNUNET_SYSERR;
+...
+
+use(a); /* 'a' points straight into the internal state of CMD2 */
+@end example
+
+
+In the Taler realm, there is also the possibility to alter the
+behaviour of supposedly well-behaved components.  This is needed
+when, for example, we want the exchange to return some corrupted
+signature in order to check if the merchant backend detects it.
+
+This alteration is accomplished by another service called @emph{twister}.
+The twister acts as a proxy between service A and B, and can be
+programmed to tamper with the data exchanged by A and B.
+
+Please refer to the Twister codebase (under the @code{test} directory)
+in order to see how to configure it.
+
+
 @node Releases
 @chapter Releases