1calcurse Test Suite 2=================== 3 4This directory holds of a couple of test cases and some helpers to simplify the 5task of creating new tests. Test cases are intended to test a specified set of 6behaviors and to avoid reintroduction of bugs that have already been fixed. The 7idea is that a new test should be added for each bug report that is received 8and for each bug that is fixed in the development branch. 9 10Running tests 11------------- 12 13The easiest way to run tests is running `make check`. This will prepare and 14compile all needed components and start all test cases. A summary is displayed 15when all tests are finished. 16 17You can also run tests manually. Test cases are usually shell scripts or 18binaries. To run an individual test, just invoke the corresponding executable. 19The `CALCURSE` and `DATA_DIR` environment variables can be used to specify an 20alternative calcurse binary and data directory. 21 22Passing another data directory might cause some failures since many tests are 23adapted for the `test/` directory provided by the test suite: 24 25 $ CALCURSE=../src/calcurse DATA_DIR="$HOME/.local/share/calcurse/" ./next-001.sh 26 Running ./next-001.sh... FAIL 27 28Writing tests 29------------- 30 31Writing test cases is as simple as creating a new shell script and adding some 32test code. Success and failure are reported by setting the exit status. Setting 33the exit status to `0` indicates success, a non-zero value indicates failure 34(which reflects the usual exit code semantics of POSIX systems). 35 36To enable a test, just add it to the `TESTS` variable in `test/Makefile.am`. If 37your test case is written in a non-interpretable language, you may need to add 38some compilation directives as well. Please note that we only accept 39POSIX-compatible shell scripts and C in mainline, so please avoid using other 40languages if you plan to get your test case integrated upstream. 41 42If your test case invokes the calcurse binary, please continue reading the 43following sections, also. 44 45The `run-test` helper 46--------------------- 47 48The `run-test` helper is a simple C program that makes writing script-based 49test cases much easier. Tests for the calcurse command line interface usually 50invoke the calcurse binary with some special command line options and compare 51the output with a hardcoded set of expected results. Unfortunately, comparing 52the output of two commands is not exactly easy in POSIX shell: this is where 53the `run-test` helper comes in handy. 54 55If you run the `run-test` helper, you can pass one or more executable files as 56parameters. The helper then invokes each of the specified scripts twice: Once 57passing `actual` as a command line parameter and once passing `expected`. It 58then compares the outputs of both invocations and checks if they are equal or 59not. If the `actual`/`expected` outputs differ for one of the programs passed 60to `run-test`, if displays `FAIL` and exits with a non-zero exit status. It 61returns success otherwise. 62 63Here is a simple example on how to use `run-test`: 64 65 #!/bin/sh 66 67 if [ "$1" = 'actual' ]; then 68 echo 'obrocodobro' | sed 's/o/a/g' 69 elif [ "$1" = 'expected' ]; then 70 echo 'abracadabra' 71 else 72 ./run-test "$0" 73 fi 74 75If the script is run without any parameters, it simply invokes `run-test`, 76passing itself as a command line parameter (see the `else` branch). `run-test` 77then reruns the script, passing `actual` as the first parameter. This starts 78the actual test (see the `if` branch). It reruns the script a second time, 79passing `expected` as the first parameter which results in the script printing 80the expected result for this test (see the `elif` branch). Finally, `run-test` 81compares both outputs, prints a message indicating whether they are equal and 82sets the exit status accordingly. This exit status is then passed on to the 83original instance of the test script and returned since `./run-test "$0"` is 84the last command that is run if the script is invoked without any parameters. 85 86You should stick to this strategy whenever you want to check the output of a 87non-interactive calcurse instance in a test. Check the following tests for some 88more examples: 89 90* `todo-001.sh` 91* `todo-002.sh` 92* `todo-003.sh` 93 94Using libfaketime 95----------------- 96 97Some tests might require faking current date and time. We currently use 98libfaketime to achieve this. Check the following files for examples: 99 100* `appointment-001.sh` 101* `next-001.sh` 102* `range-001.sh` 103* `range-002.sh` 104* `range-003.sh` 105 106NOTE: Please do not forget to check for libfaketime presence at the beginning 107of your test. Otherwise, your test is likely to fail on systems that are not 108supported by libfaketime. 109 110Additional notes 111---------------- 112 113Most tests, that invoke the calcurse binary, pass the `--read-only` parameter 114to make sure the data directory is not modified by calcurse, preventing 115unexpected side effects. Please follow this guideline if you plan to submit 116your patch upstream. 117