README.md 2.46 KB
Newer Older
1
# libgit2 tests
schu committed
2

3
These are the unit and integration tests for the libgit2 projects.
schu committed
4

5 6
* `benchmarks`
  These are benchmark tests that excercise the CLI.
7 8
* `clar`  
  This is [clar](https://github.com/clar-test/clar) the common test framework.
9 10 11
* `headertest`  
  This is a simple project that ensures that our public headers are
  compatible with extremely strict compilation options.
12
* `libgit2`  
13
  These tests exercise the core git functionality in libgit2 itself.
14
* `resources`  
15 16
  These are the resources for the tests, including files and git
  repositories.
17 18
* `util`  
  These are tests of the common utility library.
schu committed
19

20
## Writing tests for libgit2
schu committed
21

22 23
libgit2 uses the [clar test framework](http://github.com/clar-test/clar), a
C testing framework.
schu committed
24

25 26
The best resources for learning clar are [clar itself](https://github.com/clar-test/clar)
and the existing tests within libgit2.  In general:
schu committed
27

28 29 30 31 32 33
* If you place a `.c` file into a test directory, it is eligible to contain
test cases.
* The function name for your test is important; test function names begin
  with `test_`, followed by the folder path (underscore separated), two
  underscores as a delimiter, then the test name.  For example, a file
  `merge/analysis.c` may contain a test `uptodate`:
schu committed
34

35 36 37 38 39 40
  ```
  void test_merge_analysis__uptodate(void)
  {
    ...
  }
  ```
schu committed
41

42 43 44 45
* You can run an individual test by passing `-s` to the test runner.  Tests
  are referred to by their function names; for example, the function
  `test_merge_analysis__uptodate` is referred to as `merge::analysis::uptodate`.
  To run only that function you can use the `-s` option on the test runner:
schu committed
46

47 48 49
  ```
  libgit2_tests -smerge::analysis::uptodate
  ```
schu committed
50

51
## Memory leak checking
Robert Coup committed
52 53 54

These are automatically run as part of CI, but if you want to check locally:

55
### Linux
Robert Coup committed
56 57 58 59

Uses [`valgrind`](http://www.valgrind.org/):

```console
60
$ cmake -DBUILD_TESTS=ON -DVALGRIND=ON ..
Robert Coup committed
61
$ cmake --build .
62 63
$ valgrind --leak-check=full --show-reachable=yes --num-callers=50 --suppressions=../libgit2_tests.supp \
  ./libgit2_tests
Robert Coup committed
64 65
```

66
### macOS
Robert Coup committed
67 68 69 70 71

Uses [`leaks`](https://developer.apple.com/library/archive/documentation/Performance/Conceptual/ManagingMemory/Articles/FindingLeaks.html), which requires XCode installed:

```console
$ MallocStackLogging=1 MallocScribble=1 MallocLogFile=/dev/null CLAR_AT_EXIT="leaks -quiet \$PPID" \
72
  ./libgit2_tests
Robert Coup committed
73
```
74 75 76 77 78 79 80 81 82 83

### Windows

Build with the `WIN32_LEAKCHECK` option:

```console
$ cmake -DBUILD_TESTS=ON -DWIN32_LEAKCHECK=ON ..
$ cmake --build .
$ ./libgit2_tests
```