tests/README.md

   1 # libgit2 tests
   2
   3 These are the unit and integration tests for the libgit2 projects.
   4
   5 * `benchmarks`
   6   These are benchmark tests that excercise the CLI.
   7 * `clar`
   8   This is [clar](https://github.com/clar-test/clar) the common test framework.
   9 * `headertest`
  10   This is a simple project that ensures that our public headers are
  11   compatible with extremely strict compilation options.
  12 * `libgit2`
  13   These tests exercise the core git functionality in libgit2 itself.
  14 * `resources`
  15   These are the resources for the tests, including files and git
  16   repositories.
  17 * `util`
  18   These are tests of the common utility library.
  19
  20 ## Writing tests for libgit2
  21
  22 libgit2 uses the [clar test framework](http://github.com/clar-test/clar), a
  23 C testing framework.
  24
  25 The best resources for learning clar are [clar itself](https://github.com/clar-test/clar)
  26 and the existing tests within libgit2.  In general:
  27
  28 * If you place a `.c` file into a test directory, it is eligible to contain
  29 test cases.
  30 * The function name for your test is important; test function names begin
  31   with `test_`, followed by the folder path (underscore separated), two
  32   underscores as a delimiter, then the test name.  For example, a file
  33   `merge/analysis.c` may contain a test `uptodate`:
  34
  35   ```
  36   void test_merge_analysis__uptodate(void)
  37   {
  38     ...
  39   }
  40   ```
  41
  42 * You can run an individual test by passing `-s` to the test runner.  Tests
  43   are referred to by their function names; for example, the function
  44   `test_merge_analysis__uptodate` is referred to as `merge::analysis::uptodate`.
  45   To run only that function you can use the `-s` option on the test runner:
  46
  47   ```
  48   libgit2_tests -smerge::analysis::uptodate
  49   ```
  50
  51 ## Memory leak checking
  52
  53 These are automatically run as part of CI, but if you want to check locally:
  54
  55 ### Linux
  56
  57 Uses [`valgrind`](http://www.valgrind.org/):
  58
  59 ```console
  60 $ cmake -DBUILD_TESTS=ON -DVALGRIND=ON ..
  61 $ cmake --build .
  62 $ valgrind --leak-check=full --show-reachable=yes --num-callers=50 --suppressions=../libgit2_tests.supp \
  63   ./libgit2_tests
  64 ```
  65
  66 ### macOS
  67
  68 Uses [`leaks`](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/ManagingMemory/Articles/FindingLeaks.html), which requires XCode installed:
  69
  70 ```console
  71 $ MallocStackLogging=1 MallocScribble=1 MallocLogFile=/dev/null CLAR_AT_EXIT="leaks -quiet \$PPID" \
  72   ./libgit2_tests
  73 ```
  74
  75 ### Windows
  76
  77 Build with the `WIN32_LEAKCHECK` option:
  78
  79 ```console
  80 $ cmake -DBUILD_TESTS=ON -DWIN32_LEAKCHECK=ON ..
  81 $ cmake --build .
  82 $ ./libgit2_tests
  83 ```