diff options
Diffstat (limited to 'tests/README.md')
| -rw-r--r-- | tests/README.md | 99 |
1 files changed, 67 insertions, 32 deletions
diff --git a/tests/README.md b/tests/README.md index b1d70d3bc..460e045e3 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,48 +1,83 @@ -Writing Clar tests for libgit2 -============================== - -For information on the Clar testing framework and a detailed introduction -please visit: - -https://github.com/vmg/clar - - -* Write your modules and tests. Use good, meaningful names. - -* Make sure you actually build the tests by setting: - - cmake -DBUILD_CLAR=ON build/ - -* Test: - - ./build/libgit2_clar - -* Make sure everything is fine. - -* Send your pull request. That's it. - - -Memory leak checks ------------------- +# libgit2 tests + +These are the unit and integration tests for the libgit2 projects. + +* `benchmarks` + These are benchmark tests that excercise the CLI. +* `clar` + This is [clar](https://github.com/clar-test/clar) the common test framework. +* `headertest` + This is a simple project that ensures that our public headers are + compatible with extremely strict compilation options. +* `libgit2` + These tests exercise the core git functionality in libgit2 itself. +* `resources` + These are the resources for the tests, including files and git + repositories. +* `util` + These are tests of the common utility library. + +## Writing tests for libgit2 + +libgit2 uses the [clar test framework](http://github.com/clar-test/clar), a +C testing framework. + +The best resources for learning clar are [clar itself](https://github.com/clar-test/clar) +and the existing tests within libgit2. In general: + +* 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`: + + ``` + void test_merge_analysis__uptodate(void) + { + ... + } + ``` + +* 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: + + ``` + libgit2_tests -smerge::analysis::uptodate + ``` + +## Memory leak checking These are automatically run as part of CI, but if you want to check locally: -#### Linux +### Linux Uses [`valgrind`](http://www.valgrind.org/): ```console -$ cmake -DBUILD_CLAR=ON -DVALGRIND=ON .. +$ cmake -DBUILD_TESTS=ON -DVALGRIND=ON .. $ cmake --build . -$ valgrind --leak-check=full --show-reachable=yes --num-callers=50 --suppressions=../libgit2_clar.supp \ - ./libgit2_clar +$ valgrind --leak-check=full --show-reachable=yes --num-callers=50 --suppressions=../libgit2_tests.supp \ + ./libgit2_tests ``` -#### macOS +### macOS 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" \ - ./libgit2_clar + ./libgit2_tests +``` + +### Windows + +Build with the `WIN32_LEAKCHECK` option: + +```console +$ cmake -DBUILD_TESTS=ON -DWIN32_LEAKCHECK=ON .. +$ cmake --build . +$ ./libgit2_tests ``` |