Merge branch 'master' into STABLE-BRANCH-2-2
[gnupg.git] / tests / openpgp / README
1 #                                   Emacs, this is an -*- org -*- file.
2
3 * How to run the test suite
4 ** using the legacy driver
5 On POSIX you can just use
6
7   $ make -C tests/openpgp check
8
9 or
10
11   $ make -C tests/openpgp check TESTS="setup.scm your-test.scm finish.scm"
12
13 as before.
14 ** using the Scheme driver
15 This is a bit tricky because one needs to manually set some
16 environment variables.  We should make that easier.  See discussion
17 below.  From your build directory, do:
18
19   obj $ srcdir=<path to>/tests/openpgp \
20         GPGSCM_PATH=<path to>/tests/gpgscm:<path to>/tests/openpgp \
21         $(pwd)/tests/gpgscm/gpgscm [gpgscm args] \
22         run-tests.scm [test suite runner args]
23
24 *** Arguments supported by the test suite runner
25 The test suite runner supports four modes of operation,
26 {sequential,parallel}x{isolated,shared}.  You can select the mode of
27 operation using a combination of the flags --parallel, --sequential,
28 --shared, and --isolated.
29
30 By default the tests are run in sequential order, each one in a clean
31 environment.
32
33 You can specify the tests to run as positional arguments relative to
34 srcdir (e.g. just 'version.scm').  By default all tests listed in
35 run-tests.scm are executed.  Note that you do not have to specify
36 setup.scm and finish.scm, they are executed implicitly.
37
38 The test suite runner can be executed in any location that the current
39 user can write to.  It will create temporary files and directories,
40 but will in general clean up all of them.
41 *** Discussion of the various environment variables
42 **** srcdir
43 Must be set to the source of the openpgp test suite.  Used to locate
44 data files.
45 **** GPGSCM_PATH
46 Used to locate the Scheme library as well as code used by the test
47 suite.
48 **** BIN_PREFIX
49 The test suite does not hardcode any paths to tools.  If set it is
50 used to locate the tools to test, otherwise the test suite assumes to
51 be run from the build directory.
52 **** MKTDATA and GPG_PRESET_PASSPHRASE
53 These two tools are not installed by 'make install', hence we need to
54 explicitly override their position.  In fact, the location of any tool
55 used by the test suite can be overridden this way.  See defs.scm.
56 **** argv[0]
57 run-tests.scm depends on being able to re-exec gpgscm.  It uses
58 argv[0] for that.  Therefore you must use an absolute path to invoke
59 gpgscm.
60 * How to write tests
61 gpgscm provides a number of functions to aid you in writing tests, as
62 well as bindings to process management abstractions provided by GnuPG.
63 For the Scheme environment provided by TinySCHEME, see the TinySCHEME
64 manual that is included in tests/gpgscm/Manual.txt.
65
66 For a quick start, please have a look at various tests that are
67 already implemented, e.g. 'encrypt.scm'.
68 ** The test framework
69 The functions info, error, and skip display their first argument and
70 flush the output buffers.  error and skip will also terminate the
71 process, signaling that the test failed or should be skipped.
72
73 (for-each-p msg proc list) will display msg, and call proc with each
74 element of list while displaying the progress appropriately.
75 for-each-p' is similar, but accepts another callback before the 'list'
76 argument to format each item.  for-each-p can be safely nested, and
77 the inner progress indicator will be abbreviated using '.'.
78 ** Temporary files
79 (lettmp <bindings> <body>) will create and delete temporary files that
80 you can use in <body>.  (with-temporary-working-directory <body>) will
81 create a temporary director, change to that, and clean it up after
82 executing <body>).
83
84 make-temporary-file will create a temporary file.  You can optionally
85 provide an argument to that function that will serve as tag so you can
86 distinguish the files for debugging.  remove-temporary-file will
87 delete a file created using make-temporary-file.
88
89 ** Monadic transformer and pipe support
90 Tests often perform sequential transformations on files, or connect
91 processes using pipes.  To aid you in this, the test framework
92 provides two monadic data structures.
93
94 (Currently, the implementation mashes the 'bind' operation together
95 with the application of the monad.  Also, there is no 'return'
96 operation.  I guess all of that could be implemented on top of
97 call/cc, but it isn't at the moment.)
98 *** pipe
99 The pipe monad constructs pipe lines.  It consists of a function
100 pipe:do that binds the functions together and manages the execution of
101 the child processes, a family of functions that act as sources, a
102 function to spawn processes, and a family of functions acting as
103 sinks.
104
105 Sources are pipe:open, pipe:defer, pipe:echo.  To spawn a process use
106 pipe:spawn, or the convenience function pipe:gpg.  To sink the data
107 use pipe:splice, or pipe:write-to.
108
109 Example:
110
111   (pipe:do
112     (pipe:echo "3\n1\n2\n")
113     (pipe:spawn '("/usr/bin/sort"))
114     (pipe:write-to "sorted" (logior O_WRONLY O_CREAT) #o600))
115
116 Caveats: Due to the single-threaded nature of gpgscm you cannot use
117 both a source and sink that is implemented in Scheme.  pipe:defer and
118 pipe:echo are executing in gpgscm, and so does pipe:splice.
119 *** tr
120 The transformer monad describes sequential file transformations.
121
122 There is one source function, tr:open.  To describe a transformation
123 using some process, use tr:spawn, tr:gpg, or tr:pipe-do.  There are
124 several sinks, although sink is not quite the right term, because the
125 data is not consumed, and hence one can use them at any position.  The
126 "sinks" are tr:write-to, tr:call-with-content, tr:assert-identity, and
127 tr:assert-weak-identity.
128
129 A somewhat contrived example demonstrating many functions is:
130
131   (tr:do
132     (tr:pipe-do
133       (pipe:echo "3\n1\n2\n")
134       (pipe:spawn '("/usr/bin/sort")))
135     (tr:write-to "reference")
136     (tr:call-with-content
137      (lambda (c)
138        (echo "currently, c contains" (string-length c) "bytes")))
139     (tr:spawn "" '("/usr/bin/gcc" -x c "-E" -o **out** **in**))
140     (tr:pipe-do
141       (pipe:spawn '("/bin/grep" -v "#")))
142     (tr:assert-identity "reference"))
143
144 Caveats: As a convenience, gpgscm allows one to specify command line
145 arguments as Scheme symbols.  Scheme symbols, however, are
146 case-insensitive, and get converted to lower case.  Therefore, the -E
147 argument must be given as a string in the example above.  Similarly,
148 you need to quote numerical values.
149 ** Process management
150 If you just need to execute a single command, there is (call-with-fds
151 cmdline infd outfd errfd) which executes cmdline with the given file
152 descriptors bound to it, and waits for its completion returning the
153 status code.  There is (call cmdline) which is similar, but calls the
154 command with a closed stdin, connecting stdout and stderr to stderr if
155 gpgscm is executed with --verbose.  (call-check cmdline) raises an
156 exception if the command does not return 0.
157
158 (call-popen cmdline input) calls a command, writes input to its stdin,
159 and returns any output from stdout, or raises an exception containing
160 stderr on failure.
161 * Sample messages