1.  Automatic Test Discovery

1.1.  Forgot to add your test?

When we write a new test we focus on the details about the test we are trying to write. And writing tests are no trivial matter so this might well take a lot of brain power.

So, it comes as no big surprise, that sometimes you write your test you forget to add it to the suite. When we run it it appears that it passed on the first try! Although this should really make you suspicious, sometimes you get so happy that you just continue with churning out more tests and more code. It’s not until some (possibly looong) time later that you realize, after much headache and debugging, that the test did not actually pass. It was never even run!

There are practices to minimize the risk of this happening, such as always running the test as soon as you can set up the test. This way you will see it fail before trying to get it to pass.

But it is still a practice, something we, as humans, might fail to do at some point. Usually this happens when we are most stressed and in need of certainty.

1.2.  The solution - the cgreen-runner

Cgreen gives you a tool to avoid not only the risk of this happening, but also the extra work and extra code. It is called the cgreen-runner.

The cgreen-runner should come with your Cgreen installation if your platform supports the technique that is required, which is programatic access to dynamic loading of libraries. This means that a program can load an external library of code into memory and inspect it. Kind of self-inspection, or reflexion.

So all you have to do is to build a dynamically loadable library of all tests (and of course your objects under test and other necessary code). Then you can run the cgreen-runner and point it to the library. The runner will then load the library, enumerate all tests in it, and run every test.

It’s automatic, and there is nothing to forget.

1.3.  Using the runner

Assuming your tests are in first_test.c the typical command to build your library using gcc would be

$ gcc -o first_test.o -fPIC first_test.c
$ gcc -shared -o first_test.o -lcgreen

The -fPIC means to generate position independent code which is required if you want to load the library dynamically.

How to build a dynamically loadable shared library might vary a lot depending on your platform. Can’t really help you there, sorry!

Now we can run the tests using the cgreen-runner:

$ cgreen-runner first_test.dll
Discovered: 2 tests
Opening [first_test.dll] to run all discovered tests ...
Running "main" (2 tests)...
first_test.c:8: Test Failure: -> this_test_should_fail
        Expected [0] to be true
Completed "main": 1 pass, 1 failure, 0 exceptions.

More or less exactly the same output as when we ran our first test in the beginning of this quickstart tutorial.

Now we can actually delete the main function in our source code. We don’t need all this:

int main(int argc, char **argv) {
    TestSuite *suite = create_test_suite();
    add_test(suite, this_test_should_pass);
    add_test(suite, this_test_should_fail);
    return run_test_suite(suite, create_text_reporter());

It always feel good to delete code, right?

We can also select which test to run:

$ cgreen-runner.exe first_test.dll this_test_should_fail
Discovered: 2 tests
Opening [first_test.dll] to only run test 'this_test_should_fail' ...
Running "main" (2 tests)...
first_test.c:8: Test Failure: -> this_test_should_fail
        [0] should be true
Completed "main": 0 passes, 1 failure, 0 exceptions.

1.4.  Setup, Teardown and custom reporters

If you need setup and teardown functions with the runner you need to go to the BDD style using BeforeEach() and AfterEach() as described in Changing Style above.

Neither is it possible to use custom reporters as outlined in the previous chapter.

In both these cases you need to resort to the standard, programatic, way of invoking your tests. But, who knows…