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