Problems getting started with clar (stale documentation)

[cknadler]

Problems getting started with clar (stale documentation)

[vmg]

Damn right, the docs are unfortunately out of date. Let me whip up an update during today's flight. Thanks for your patience!

[arrbee]

So, while @vmg is writing, some quick tips:

1. Make a test folder in your project
2. Copy clar.c, clar.h, and the clar/ folder into the root of the test
   folder. I suspect you could also figure out a way to use submodules for
   this, but we generally don't.
3. Write a main.c for your test application. You can use
   https://github.com/vmg/clar/blob/master/test/main.c as a starting point
   and add in any special initialization and/or teardown that you need.
   You can see an example of this in a "real world" project at
   https://github.com/libgit2/libgit2/blob/development/tests-clar/main.c
4. Actually writing tests is still pretty much as documented in the
   README. You create files with your tests organized however you like using
   the clar naming conventions as documented. Again, you can look at
   https://github.com/vmg/clar/blob/master/test/sample.c for an example. The
   test functions are named test_<path_with_underscores>__<testname>. So,
   if you make a folder named "basics" and a file named "strings.c", the
   tests in that file would be void test_basics_strings__mytest(void) {}.
   You can also use the "magic" functions test_basics_strings__initialize
   which will be called before each test and test_basics_strings__cleanup
   which will be called after each test.
5. Set up your build. Clar doesn't mandate a particular build system, but
   before compilation you should run python generate.py . from the test
   folder that you made in step one. That will generate the clar.suite
   file which will be included by clar.c. Your Makefile / whatever-you-use
   should include the library you are testing, plus clar.c, all of the .c
   files in the clar/ folder, and all of your test files, and should build a
   command line executable. Again, you can see a pretty rudimentary version
   of all this in https://github.com/vmg/clar/blob/master/test/Makefile
6. If you need mutable test data, you will probably want to use clar
   fixtures. For that, you will need to define CLAR_FIXTURE_PATH when you
   build the library to be the full path to the root of the test data
   area. If you define that during the build, you will be able to use
   cl_fixture_sandbox() and cl_fixture_cleanup() to clone the test data
   for each test and to clean it up after. You can also use cl_fixture
   just to get a path to the test data if you don't need to clone it. If you
   are not using mutable test data that needs to be sandboxed for each test,
   then this may not be important to you.

Anyhow, hopefully that helps (and hopefully I didn't forget any steps).

[cknadler]

Damn right, the docs are unfortunately out of date. Let me whip up an update during today's flight. Thanks for your patience!

Thanks for all the hard work. Looking forward to using clar. 😄

So, while @vmg is writing, some quick tips:

Awesome. This is exactly what I was looking for. 👍