tests: Dump the tools that the tests are going to use.
[gnupg.git] / tests / openpgp / README
index 498d5f5..b9d5607 100644 (file)
@@ -1,17 +1,31 @@
-Emacs, this is an -*- org -*- file.
+#                                   Emacs, this is an -*- org -*- file.
 
 * How to run the test suite
-** using the legacy driver
-On POSIX you can just use
+From your build directory, run
 
-  $ make -C tests/openpgp check
+  obj $ make -C tests/openpgp check
 
-or
+to run all tests or
 
-  $ make -C tests/openpgp check TESTS="setup.scm your-test.scm finish.scm"
+  obj $ make -C tests/openpgp check XTESTS=your-test.scm
 
-as before.
-** using the Scheme driver
+to run a specific test (or any number of tests separated by spaces).
+
+If you want to debug a test, add verbose=1 to see messages printed by
+spawned programs to their standard error stream, verbose=2 to see what
+programs are executed, or verbose=3 to see even more program output
+and exit codes.
+
+** Passing options to the test driver
+
+You can set TESTFLAGS to pass flags to 'run-tests.scm'.  For example,
+to speed up the test suite when bisecting, do
+
+  obj $ make -C tests/openpgp check TESTFLAGS=--parallel
+
+See below for the arguments supported by the driver.
+
+** Calling the test driver directly
 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:
@@ -22,18 +36,13 @@ below.  From your build directory, do:
         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,
@@ -75,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
@@ -158,3 +214,4 @@ exception if the command does not return 0.
 (call-popen cmdline input) calls a command, writes input to its stdin,
 and returns any output from stdout, or raises an exception containing
 stderr on failure.
+* Sample messages