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