tests: Dump the tools that the tests are going to use.
[gnupg.git] / tests / openpgp / README
index 84faf1c..b9d5607 100644 (file)
@@ -30,24 +30,19 @@ This is a bit tricky because one needs to manually set some
 environment variables.  We should make that easier.  See discussion
 below.  From your build directory, do:
 
-  obj $ TMP=/tmp srcdir=<path to>/tests/openpgp \
+  obj $ srcdir=<path to>/tests/openpgp \
         GPGSCM_PATH=<path to>/tests/gpgscm:<path to>/tests/openpgp \
         $(pwd)/tests/gpgscm/gpgscm [gpgscm args] \
         run-tests.scm [test suite runner args]
 
 *** Arguments supported by the test suite runner
-The test suite runner supports four modes of operation,
-{sequential,parallel}x{isolated,shared}.  You can select the mode of
-operation using a combination of the flags --parallel, --sequential,
---shared, and --isolated.
-
-By default the tests are run in sequential order, each one in a clean
-environment.
+The test suite runner supports two modes of operation, '--sequential'
+and '--parallel'.  By default the tests are run in sequential order,
+each one in a clean environment.
 
 You can specify the tests to run as positional arguments relative to
-srcdir (e.g. just 'version.scm').  By default all tests listed in
-run-tests.scm are executed.  Note that you do not have to specify
-setup.scm and finish.scm, they are executed implicitly.
+srcdir (e.g. just 'version.scm').  Note that you do not have to
+specify setup.scm and finish.scm, they are executed implicitly.
 
 The test suite runner can be executed in any location that the current
 user can write to.  It will create temporary files and directories,
@@ -89,6 +84,53 @@ element of list while displaying the progress appropriately.
 for-each-p' is similar, but accepts another callback before the 'list'
 argument to format each item.  for-each-p can be safely nested, and
 the inner progress indicator will be abbreviated using '.'.
+** Debugging tests
+
+Say you are working on a new test called 'your-test.scm', you can run
+it on its own using
+
+  obj $ make -C tests/openpgp check XTESTS=your-test.scm
+
+but something isn't working as expected.  There are several little
+gadgets that might help.  The first one is 'trace', a function that
+prints the value given to it and evaluates to it.  E.g.
+
+  (trace (+ 2 3))
+
+prints '5' and evaluates to 5.  Also, there is an 'assert' macro that
+aborts the execution if its argument does not evaluate to a trueish
+value.  Feel free to express invariants with it.
+
+You can also get an interactive repl by dropping
+
+  (interactive-repl (current-environment))
+
+anywhere you like.  Or, if you want to examine the environment from an
+operating system shell, use
+
+  (interactive-shell)
+
+** Interfacing with gpg
+
+defs.scm defines several convenience functions.  Say you want to parse
+the colon output from gpg, there is gpg-with-colons that splits the
+result at newlines and colons, so you can use the result like this:
+
+ (define (fpr some-key)
+   (list-ref (assoc "fpr" (gpg-with-colons
+                          `(--with-fingerprint
+                            --list-secret-keys ,some-key)))
+            9))
+
+Or if you want to count all non-revoked uids for a given key, do
+
+ (define (count-uids-of-secret-key some-key)
+   (length (filter (lambda (x) (and (string=? "uid" (car x))
+                                   (string=? "u" (cadr x))))
+                  (gpg-with-colons
+                   `(--with-fingerprint
+                     --list-secret-keys ,some-key)))))
+
 ** Temporary files
 (lettmp <bindings> <body>) will create and delete temporary files that
 you can use in <body>.  (with-temporary-working-directory <body>) will