README.md (3458B)
1 c-ares Unit Test Suite 2 ====================== 3 4 This directory holds unit tests for the c-ares library. To build the tests: 5 6 - Build the main c-ares library first, in the directory above this. To 7 enable tests of internal functions, configure the library build to expose 8 hidden symbols with `./configure --disable-symbol-hiding`. 9 - Generate a `configure` file by running `autoreconf -iv` (which requires 10 a local installation of 11 [autotools](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html)). 12 - `./configure` 13 - `make` 14 - Run the tests with `./arestest`, or `./arestest -v` for extra debug info. 15 16 Points to note: 17 18 - The tests are written in C++11, and so need a C++ compiler that supports 19 this. To avoid adding this as a requirement for the library, the 20 configuration and build of the tests is independent from the library. 21 - The tests include some live queries, which will fail when run on a machine 22 without internet connectivity. To skip live tests, run with 23 `./arestest --gtest_filter=-*.Live*`. 24 - The tests include queries of a mock DNS server. This server listens on port 25 5300 by default, but the port can be changed with the `-p 5300` option to 26 `arestest`. 27 28 29 Test Types 30 ---------- 31 32 The test suite includes various different types of test. 33 34 - There are live tests (`ares-test-live.cc`), which assume that the 35 current machine has a valid DNS setup and connection to the 36 internet; these tests issue queries for real domains but don't 37 particularly check what gets returned. The tests will fail on 38 an offline machine. 39 - There are some mock tests (`ares-test-mock.cc`) that set up a fake DNS 40 server and inject its port into the c-ares library configuration. 41 These tests allow specific response messages to be crafted and 42 injected, and so are likely to be used for many more tests in 43 future. 44 - To make this generation/injection easier, the `dns-proto.h` 45 file includes C++ helper classes for building DNS packets. 46 - Other library entrypoints that don't require network activity 47 (e.g. `ares_parse_*_reply`) are tested directly. 48 - A couple of the tests use a helper method of the test fixture to 49 inject memory allocation failures, using a recent change to the 50 c-ares library that allows override of `malloc`/`free`. 51 - There are some tests of the internal entrypoints of the library 52 (`ares-test-internal.c`), but these are only enabled if the library 53 was configured with `--disable-symbol-hiding` and/or 54 `--enable-expose-statics`. 55 - There is also an entrypoint to allow Clang's 56 [libfuzzer](http://llvm.org/docs/LibFuzzer.html) to drive 57 the packet parsing code in `ares_parse_*_reply`, together with a 58 standalone wrapper for it (`./aresfuzz`) to allow use of command 59 line fuzzers (such as [afl-fuzz](http://lcamtuf.coredump.cx/afl/)) 60 for further [fuzz testing](#fuzzing). 61 62 63 Code Coverage Information 64 ------------------------- 65 66 To generate code coverage information: 67 68 - Configure both the library and the tests with `./configure 69 --enable-code-coverage` before building. This requires the relevant code 70 coverage tools ([gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html), 71 [lcov](http://ltp.sourceforge.net/coverage/lcov.php)) to be installed locally. 72 - Run the tests with `test/arestest`. 73 - Generate code coverage output with `make code-coverage-capture` in the 74 library directory (i.e. not in `test/`). 75