1# Testing PackCC 2 3## How to run the tests 4 5For running the tests, we assume you have `bats-core` and `uncrustify`. 6 7If you do not have `bats-core` installed, you can do it using your package manager or from its tarball: 8``` 9$ curl -L -o bats-core-1.2.1.tar.gz https://github.com/bats-core/bats-core/archive/v1.2.1.tar.gz && 10 tar zxvf bats-core-1.2.1.tar.gz && 11 cd bats-core-1.2.1 && 12 sudo ./install.sh /usr/local 13``` 14 15If you do not have `uncrustify` installed, you can do it using your package manager or from its repository: 16``` 17$ git clone https://github.com/uncrustify/uncrustify && 18 cd uncrustify && 19 mkdir -p build && 20 cd build && 21 cmake .. && 22 make && 23 sudo make install 24``` 25 26When you use MinGW-w64, `cmake` requires the options `-G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX=/usr/local`. 27 28After installing `bats-core-1.2.1` and `uncrustify`, you can run the tests using `tests/test.sh` script: 29``` 30$ ./test.sh 31 ✓ Testing basic.d - generation 32 ✓ Testing basic.d - compilation 33 ✓ Testing basic.d - run 34 ... 35 ✓ Testing strings.d - generation 36 ✓ Testing strings.d - compilation 37 ✓ Testing strings.d - run 38 ✓ Testing strings.d - run [utf8] 39 4019 tests, 0 failures, 1 skipped 41``` 42 43The script passes all its arguments to `bats`, for example to run only some tests, 44you can call it with `--filter <regexp>`. To see all the available arguments, execute `tests/test.sh --help`. 45 46The behavior of the `test.sh` can also be influenced by environment variables: 47 - `PACKCC` - Path to a compiled `packcc` binary. If unset, the script will compile it before running the tests. 48 - `CC` - Compiler to use to compile `packcc` (if necessary) and the programs for testing. Defaults to `cc`. 49 50## How to write a generic test 51 52To create a new test, just follow these simple steps: 53 541. Create a directory with suitable name, e.g.: `tests/sequence.d`. 552. Create a grammar file called `input.peg` in this directory. 563. Create one or more input files. The files must match the glob pattern `input*.txt`. 574. Create a file with expected output for each of the inputs. The names must match the input, 58 just replace "input" with "expected". E.g.: for `input-1.txt`, there must be `expected-1.txt`. 59 60Each test automatically performs three or more test cases: 61 621. Generates a parser from the `input.peg` grammar. 632. Compiles the generated parser. 643. Runs the parser with specified inputs, comparing the outputs with the contents of the respective expected files. 65 66## How to write a customized test 67 68Sometimes the auto-generated test is not exactly what you need. In this case, you can simply create a customized test on your own: 69 701. Create a directory with a suitable name, e.g.: `tests/sequence.d`. 712. Create one or more `*.bats` files in this directory. 723. Specify a custom test in the bats file. 73 74The test script will notice the customized files and will not generate a generic one. 75However, you can still reuse as much of the common code as you want simply by loading `tests/utils.sh` 76and calling the prepared functions. See [calc.d/calc.bats](calc.d/calc.bats) as an example. 77 78## How to skip a test input 79 80*Note: This paragraph applies only to automatically generated tests. For customized tests, 81just add `skip` directive to your* `*.bats` *file as needed.* 82 83Sometimes it is useful to skip a test input, for example to avoid an input that triggers a known bug 84that has not yet been fixed. To do so, simply rename the input file to `input*.skip.txt`. 85 86If you want to skip all test inputs in the directory, rename the grammar file to `input.skip.peg`. 87