README.md
1# Test suite
2
3The test suite consists of a shell script `pick-test.sh` responsible for running
4tests written in the file format described below and `pick-test.c` which will
5invoke pick with a pseudo-terminal.
6This allows sending keyboard input sequences and reading the output on exit.
7
8The recommended way to run the test suite is using `make(1)`:
9
10```sh
11$ make test
12```
13
14Use the `-j` option with a value matching the number of cores on your machine to
15speed-up the process:
16
17```sh
18$ make -jN test
19```
20
21To run one or more specific tests:
22
23```sh
24$ env TESTS=01.t make -e test
25```
26
27## Format of test files
28
29A test file consist of one or many tests,
30separated by a blank line.
31Each test consist of fields where field names are terminated with `:` and the
32rest of line is recognized as the corresponding field value.
33Some fields allow multi-line values.
34Everything after `#` and up to the next newline is treated as a comment.
35
36A trivial example:
37
38```
39description: select the first choice
40keys: \n
41stdin:
421
432
44stdout:
451
46```
47
48The following fields are recognized:
49
50- `args`
51
52 Arguments passed to the pick process as is.
53
54- `description`
55
56 Purpose of the test.
57
58- `env`
59
60 Variables set in the environment before the pick process is
61 started.
62 The variables are specified as `name=value` separated by space,
63 see `env(1)`.
64
65- `exit`
66
67 Exit code of the pick process,
68 defaults to `0` if omitted.
69
70- `keys`
71
72 Sequence of characters sent as keyboard input to the pick process.
73 The value will be sent through `printf(1)` prior sending it to the pick
74 process.
75 Spaces will be stripped,
76 if not escaped as `\\ `.
77
78 The test suite is executed with `TERM=xterm`,
79 therefore make sure to only use the corresponding value for a given capability
80 as defined by the xterm terminfo database.
81 Given a capability,
82 the value can be retrieved using `infocmp(1)`:
83
84 ```sh
85 $ infocmp -1 xterm | grep khome
86 ```
87
88- `stdin`
89
90 Multi-line input to the pick process.
91
92- `stdout`
93
94 Expected multi-line output from the pick process.
95 If omitted,
96 output assertion is not performed.
97