tests/openpgp/README

   1 #                                   Emacs, this is an -*- org -*- file.
   2
   3 * How to run the test suite
   4 From your build directory, run
   5
   6   obj $ make -C tests/openpgp check
   7
   8 to run all tests or
   9
  10   obj $ make -C tests/openpgp check XTESTS=your-test.scm
  11
  12 to run a specific test (or any number of tests separated by spaces).
  13
  14 If you want to debug a test, add verbose=1 to see messages printed by
  15 spawned programs to their standard error stream, verbose=2 to see what
  16 programs are executed, or verbose=3 to see even more program output
  17 and exit codes.
  18
  19 ** Passing options to the test driver
  20
  21 You can set TESTFLAGS to pass flags to 'run-tests.scm'.  For example,
  22 to speed up the test suite when bisecting, do
  23
  24   obj $ make -C tests/openpgp check TESTFLAGS=--parallel
  25
  26 See below for the arguments supported by the driver.
  27
  28 ** Calling the test driver directly
  29 This is a bit tricky because one needs to manually set some
  30 environment variables.  We should make that easier.  See discussion
  31 below.  From your build directory, do:
  32
  33   obj $ TMP=/tmp srcdir=<path to>/tests/openpgp \
  34         GPGSCM_PATH=<path to>/tests/gpgscm:<path to>/tests/openpgp \
  35         $(pwd)/tests/gpgscm/gpgscm [gpgscm args] \
  36         run-tests.scm [test suite runner args]
  37
  38 *** Arguments supported by the test suite runner
  39 The test suite runner supports two modes of operation, '--sequential'
  40 and '--parallel'.  By default the tests are run in sequential order,
  41 each one in a clean environment.
  42
  43 You can specify the tests to run as positional arguments relative to
  44 srcdir (e.g. just 'version.scm').  Note that you do not have to
  45 specify setup.scm and finish.scm, they are executed implicitly.
  46
  47 The test suite runner can be executed in any location that the current
  48 user can write to.  It will create temporary files and directories,
  49 but will in general clean up all of them.
  50 *** Discussion of the various environment variables
  51 **** srcdir
  52 Must be set to the source of the openpgp test suite.  Used to locate
  53 data files.
  54 **** GPGSCM_PATH
  55 Used to locate the Scheme library as well as code used by the test
  56 suite.
  57 **** BIN_PREFIX
  58 The test suite does not hardcode any paths to tools.  If set it is
  59 used to locate the tools to test, otherwise the test suite assumes to
  60 be run from the build directory.
  61 **** MKTDATA and GPG_PRESET_PASSPHRASE
  62 These two tools are not installed by 'make install', hence we need to
  63 explicitly override their position.  In fact, the location of any tool
  64 used by the test suite can be overridden this way.  See defs.scm.
  65 **** argv[0]
  66 run-tests.scm depends on being able to re-exec gpgscm.  It uses
  67 argv[0] for that.  Therefore you must use an absolute path to invoke
  68 gpgscm.
  69 * How to write tests
  70 gpgscm provides a number of functions to aid you in writing tests, as
  71 well as bindings to process management abstractions provided by GnuPG.
  72 For the Scheme environment provided by TinySCHEME, see the TinySCHEME
  73 manual that is included in tests/gpgscm/Manual.txt.
  74
  75 For a quick start, please have a look at various tests that are
  76 already implemented, e.g. 'encrypt.scm'.
  77 ** The test framework
  78 The functions info, error, and skip display their first argument and
  79 flush the output buffers.  error and skip will also terminate the
  80 process, signaling that the test failed or should be skipped.
  81
  82 (for-each-p msg proc list) will display msg, and call proc with each
  83 element of list while displaying the progress appropriately.
  84 for-each-p' is similar, but accepts another callback before the 'list'
  85 argument to format each item.  for-each-p can be safely nested, and
  86 the inner progress indicator will be abbreviated using '.'.
  87 ** Debugging tests
  88
  89 Say you are working on a new test called 'your-test.scm', you can run
  90 it on its own using
  91
  92   obj $ make -C tests/openpgp check XTESTS=your-test.scm
  93
  94 but something isn't working as expected.  There are several little
  95 gadgets that might help.  The first one is 'trace', a function that
  96 prints the value given to it and evaluates to it.  E.g.
  97
  98   (trace (+ 2 3))
  99
 100 prints '5' and evaluates to 5.  Also, there is an 'assert' macro that
 101 aborts the execution if its argument does not evaluate to a trueish
 102 value.  Feel free to express invariants with it.
 103
 104 You can also get an interactive repl by dropping
 105
 106   (interactive-repl (current-environment))
 107
 108 anywhere you like.  Or, if you want to examine the environment from an
 109 operating system shell, use
 110
 111   (interactive-shell)
 112
 113 ** Interfacing with gpg
 114
 115 defs.scm defines several convenience functions.  Say you want to parse
 116 the colon output from gpg, there is gpg-with-colons that splits the
 117 result at newlines and colons, so you can use the result like this:
 118
 119  (define (fpr some-key)
 120    (list-ref (assoc "fpr" (gpg-with-colons
 121                            `(--with-fingerprint
 122                              --list-secret-keys ,some-key)))
 123              9))
 124
 125 Or if you want to count all non-revoked uids for a given key, do
 126
 127  (define (count-uids-of-secret-key some-key)
 128    (length (filter (lambda (x) (and (string=? "uid" (car x))
 129                                     (string=? "u" (cadr x))))
 130                    (gpg-with-colons
 131                     `(--with-fingerprint
 132                       --list-secret-keys ,some-key)))))
 133
 134 ** Temporary files
 135 (lettmp <bindings> <body>) will create and delete temporary files that
 136 you can use in <body>.  (with-temporary-working-directory <body>) will
 137 create a temporary director, change to that, and clean it up after
 138 executing <body>).
 139
 140 make-temporary-file will create a temporary file.  You can optionally
 141 provide an argument to that function that will serve as tag so you can
 142 distinguish the files for debugging.  remove-temporary-file will
 143 delete a file created using make-temporary-file.
 144
 145 ** Monadic transformer and pipe support
 146 Tests often perform sequential transformations on files, or connect
 147 processes using pipes.  To aid you in this, the test framework
 148 provides two monadic data structures.
 149
 150 (Currently, the implementation mashes the 'bind' operation together
 151 with the application of the monad.  Also, there is no 'return'
 152 operation.  I guess all of that could be implemented on top of
 153 call/cc, but it isn't at the moment.)
 154 *** pipe
 155 The pipe monad constructs pipe lines.  It consists of a function
 156 pipe:do that binds the functions together and manages the execution of
 157 the child processes, a family of functions that act as sources, a
 158 function to spawn processes, and a family of functions acting as
 159 sinks.
 160
 161 Sources are pipe:open, pipe:defer, pipe:echo.  To spawn a process use
 162 pipe:spawn, or the convenience function pipe:gpg.  To sink the data
 163 use pipe:splice, or pipe:write-to.
 164
 165 Example:
 166
 167   (pipe:do
 168     (pipe:echo "3\n1\n2\n")
 169     (pipe:spawn '("/usr/bin/sort"))
 170     (pipe:write-to "sorted" (logior O_WRONLY O_CREAT) #o600))
 171
 172 Caveats: Due to the single-threaded nature of gpgscm you cannot use
 173 both a source and sink that is implemented in Scheme.  pipe:defer and
 174 pipe:echo are executing in gpgscm, and so does pipe:splice.
 175 *** tr
 176 The transformer monad describes sequential file transformations.
 177
 178 There is one source function, tr:open.  To describe a transformation
 179 using some process, use tr:spawn, tr:gpg, or tr:pipe-do.  There are
 180 several sinks, although sink is not quite the right term, because the
 181 data is not consumed, and hence one can use them at any position.  The
 182 "sinks" are tr:write-to, tr:call-with-content, tr:assert-identity, and
 183 tr:assert-weak-identity.
 184
 185 A somewhat contrived example demonstrating many functions is:
 186
 187   (tr:do
 188     (tr:pipe-do
 189       (pipe:echo "3\n1\n2\n")
 190       (pipe:spawn '("/usr/bin/sort")))
 191     (tr:write-to "reference")
 192     (tr:call-with-content
 193      (lambda (c)
 194        (echo "currently, c contains" (string-length c) "bytes")))
 195     (tr:spawn "" '("/usr/bin/gcc" -x c "-E" -o **out** **in**))
 196     (tr:pipe-do
 197       (pipe:spawn '("/bin/grep" -v "#")))
 198     (tr:assert-identity "reference"))
 199
 200 Caveats: As a convenience, gpgscm allows one to specify command line
 201 arguments as Scheme symbols.  Scheme symbols, however, are
 202 case-insensitive, and get converted to lower case.  Therefore, the -E
 203 argument must be given as a string in the example above.  Similarly,
 204 you need to quote numerical values.
 205 ** Process management
 206 If you just need to execute a single command, there is (call-with-fds
 207 cmdline infd outfd errfd) which executes cmdline with the given file
 208 descriptors bound to it, and waits for its completion returning the
 209 status code.  There is (call cmdline) which is similar, but calls the
 210 command with a closed stdin, connecting stdout and stderr to stderr if
 211 gpgscm is executed with --verbose.  (call-check cmdline) raises an
 212 exception if the command does not return 0.
 213
 214 (call-popen cmdline input) calls a command, writes input to its stdin,
 215 and returns any output from stdout, or raises an exception containing
 216 stderr on failure.
 217 * Sample messages