<?xml version="1.0"?>
<page title="Cgreen Quickstart Guide" here="Cgreen">
    <long_title>
        Cgreen is a unit testing framework for the C programming language
    </long_title>
    <content>
        <section name="what" title="What is Cgreen?">
            <p>
                Cgreen is a unit tester for the C software developer.
                This is a test automation and software quality assurance tool for
                development teams.
                The tool is completely open source published under the
                <a href="http://www.gnu.org/licenses/lgpl.html">LGPL</a>.
            </p>
            <p>
                Unit testing is a development practice popularised by the
                agile development community.
                It is characterised by writing many small tests alongside
                the normal code.
                Often the tests are written before the code they are testing,
                in a tight test-code-refactor loop.
                Done this way, the practice is known as Test Driven Development.
                Cgreen supports this style of working.
            </p>
            <p>
                Unit tests are written in the same language as the code, in
                our case C.
                This avoids the mental overhead of constantly switching language,
                and also allows you to use any application code in your tests.
            </p>
            <p>
                The feature list is:
                <ul>
                    <li>Fully composable test suites.</li>
                    <li><code>setup()</code> and <code>teardown()</code> for
                        tests and test suites.</li>
                    <li>Each test runs in it's own process.</li>
                    <li>An isolated test can be run in a single process for
                        debugging.</li>
                    <li>Ability to mock functions.</li>
                    <li>The reporting mechanism can be easily extended.</li>
                </ul>
                Note that this tool is for C programming, not C++.
            </p>
        </section>
        <section name="install" title="Installing Cgreen">
            <p>
                Installing Cgreen is as simple as running <a href="http://www.gnu.org/software/make/">make</a>
                in the unzipped <em>cgreen</em> folder.
                The makefile will create a unix library called <em>cgreen.a</em>
                which can be used in conjunction with the <em>cgreen.h</em>
                header file to compile test code.
            </p>
            <p>
                We'll first write a test to confirm everything is working.
                Let's start with a simple test script with no tests, called
                <em>first_test.c</em>...
<c><![CDATA[<strong>
#include "cgreen/cgreen.h"</strong>

int main(int argc, char **argv) {<strong>
    TestSuite *suite = create_test_suite();
    return run_test_suite(suite, create_text_reporter());</strong>
}
]]></c>
                This is a very unexciting test.
                It just creates an empty test suite and runs it.
                It's usually easier to proceed in small steps, though,
                and this is the smallest one I could think of.
                The only complication is the <em>cgreen.h</em> header
                file.
                Here I am assuming we have symlinked the Cgreen folder
                into the same location as our test script, or placed
                the Cgreen folder in the path.
            </p>
            <p>
                Building this test is, of course, trivial...
<sh>
gcc -c first_test.c
gcc first_test.o cgreen/cgreen.a -o first_test
./first_test
</sh>
                Invoking the executable should give...
<sh>
Running "main"...
Completed "main": 0 passes, 0 failures, 0 exceptions.
</sh>
                All of the above rather assumes you are working in a
                Unix like environment, probably with <em>gcc</em>.
                The code is pretty much standard C99, so any C compiler
                should work.
                Cgreen should compile on all systems that support the
                <em>sys/msg.h</em> messaging library.
                This has been tested on Linux and Mac OSX so far, but
                not Windows, although that might work too.
            </p>
            <p>
                So far we have tested compilation, and that the test suite
                actually runs.
                Let's add a meaningless test or two so that you can see how
                it runs...
<c><![CDATA[
#include "cgreen/cgreen.h"
<strong>
void this_test_should_pass() {
    assert_true(1);
}

void this_test_should_fail() {
    assert_true(0);
}
</strong>
int main(int argc, char **argv) {
    TestSuite *suite = create_test_suite();<strong>
    add_test(suite, this_test_should_pass);
    add_test(suite, this_test_should_fail);</strong>
    return run_test_suite(suite, create_text_reporter());
}
]]></c>
                A test can be any function with a <code>void (void)</code>
                signature.
                <code>add_test()</code> is a macro, hence
                there is no <code>&amp;</code> with the function
                pointer.
            </p>
            <p>
                On compiling and running, we now get the output...
<sh><![CDATA[
Running "main"...
Failure!: this_test_should_fail -> Problem at [first_test.c] line [8]
Completed "main": 1 pass, 1 failure, 0 exceptions.
]]></sh>
                The <code>TextReporter</code>, created by the
                <code>create_text_reporter()</code> call, is the
                simplest way to output the test results.
                It just streams the failures as text.
                Currently it's the only method supported.
            </p>
        </section>
        <section name="tdd" title="Five minutes doing TDD with Cgreen">
            <p>
                For a more realistic example we need something to test.
                We'll pretend that we are writing a function to split
                the words of a sentence in place.
                It does this by replacing any spaces with string
                terminators and returns the number of conversions plus one.
                Here is an example of what we have in mind...
<c><![CDATA[
char *sentence = strdup("Just the first test");
word_count = split_words(sentence);
]]></c>
                <code>sentence</code> should now point at
                <code><![CDATA["Just\0the\0first\0test"]]></code>.
                Not an obviously useful function, but we'll be using it
                for something more practical below.
            </p>
            <p>
                This time around we'll add a little more structure to our tests.
                Rather than having the test as a stand alone program, we'll
                separate the runner from the test cases.
                That way, multiple test suites of test cases can be
                included in the <code>main()</code> runner file.
                This makes it less work to add more tests.
            </p>
            <p>
                Here is the, so far empty, test case in <em>words_test.c</em>...
<c><![CDATA[
#include "cgreen/cgreen.h"
<strong>
TestSuite *words_tests() {
    TestSuite *suite = create_test_suite();
    return suite;
}</strong>
]]></c>
                Here is the <em>all_tests.c</em> test runner...
<c><![CDATA[
#include "cgreen/cgreen.h"

TestSuite *words_tests();

int main(int argc, char **argv) {
    TestSuite *suite = create_test_suite();<strong>
    add_suite(suite, words_tests());</strong>
    if (argc > 1) {<strong>
        return run_single_test(suite, argv[1], create_text_reporter());</strong>
    }
    return run_test_suite(suite, create_text_reporter());
}
]]></c>
                Cgreen has two ways of running tests.
                The default is with each test run in it's own process.
                This is what happens if you invoke <code>run_test_suite()</code>.
                While this makes all the tests independent, the constant
                <code>fork()</code>'ing can make the tests difficult to debug.
                To make debugging simpler, Cgreen does not <code>fork()</code>
                when only a single test is run by name with
                <code>run_single_test()</code>.
            </p>
            <p>
                Building this scaffolding...
<sh>
gcc -c words_test.c
gcc -c all_tests.c
gcc words_test.o all_tests.o cgreen/cgreen.a -o all_tests
</sh>
                ...and executing the result gives the familiar...
<sh><![CDATA[
Running "main"...
Completed "main": 0 passes, 0 failures, 0 exceptions.
]]></sh>
                All this scaffolding is pure overhead, but from now on adding tests
                will be a lot easier.
            </p>
            <p>
                Here is a first test of <code>split_words()</code>...
<c><![CDATA[
#include "cgreen/cgreen.h"<strong>
#include "words.h"
#include <string.h>

void word_count_returned_from_split() {
    char *sentence = strdup("Birds of a feather");
    int word_count = split_words(sentence);
    assert_equal(word_count, 4);
    free(sentence);
}</strong>

TestSuite *words_tests() {
    TestSuite *suite = create_test_suite();<strong>
    add_test(suite, word_count_returned_from_split);</strong>
    return suite;
}
]]></c>
                The <code>assert_equal()</code> macro takes in the two
                values to compare.
                With the default <code>TextReporter</code> the message
                is sent to <code>STDOUT</code>.
            </p>
            <p>
                To get this to compile we need to create the <em>words.h</em>
                header file...
<c>
int split_words(char *sentence);
</c>
                ...and to get the code to link we need a stub function in
                <em>words.c</em>...
<c>
int split_words(char *sentence) {
    return 0;
}
</c>
                A full build later...
<sh>
gcc -c all_tests.c
gcc -c words_test.c
gcc -c words.c
gcc all_tests.o words_test.o words.o cgreen/cgreen.a -o all_tests
./all_tests
</sh>
                ...and we get the more useful response...
<sh><![CDATA[
Running "main"...
Failure!: words_tests -> word_count_returned_from_split ->
        [0] should match [4] at [words_test.c] line [8]
Completed "main": 0 passes, 1 failure, 0 exceptions.
]]></sh>
                The breadcrumb trail is the nesting of the tests.
                It goes from the
                test suites, which can nested in each other, through the test
                function, and finally to the message from the assertion.
                In the language of Cgreen, a failure is a mismatched
                assertion, an exception is accumulated
                when a test fails to complete for any reason.
            </p>
            <p>
                We could get this to pass just by returning the value 4.
                Doing TDD in really small steps, you would actually do this,
                but frankly this example is too simple.
                Instead we'll go straight to the refactoring...
<c><![CDATA[
<strong>#include <string.h></strong>

int split_words(char *sentence) {<strong>
    int i, count = 1;
    for (i = 0; i < strlen(sentence); i++) {
        if (sentence[i] == ' ') {
            count++;
        }
    }
    return count;</strong>
}
]]></c>
                There is a hidden problem here, but our tests still pass
                so we'll pretend we didn't notice.
            </p>
            <p>
                Time to add another test.
                We want to confirm that the string is broken into
                separate words...
<c><![CDATA[
#include "cgreen/cgreen.h"
#include "words.h"
#include <string.h>

void word_count_returned_from_split() { ... }
<strong>
void spaces_should_be_converted_to_zeroes() {
    char *sentence = strdup("Birds of a feather");
    split_words(sentence);
    int comparison = memcmp("Birds\0of\0a\0feather", sentence, strlen(sentence));
    assert_equal(comparison, 0);
    free(sentence); 
}</strong>

TestSuite *words_tests() {
    TestSuite *suite = create_test_suite();
    add_test(suite, word_count_returned_from_split);<strong>
    add_test(suite, spaces_should_be_converted_to_zeroes);</strong>
    return suite;
}
]]></c>
                Sure enough, we get a failure...
<sh><![CDATA[
Running "main"...
Failure!: words_tests -> spaces_should_be_converted_to_zeroes ->
        [-32] should match [0] at [words_test.c] line [16]
Completed "main": 1 pass, 1 failure, 0 exceptions.
]]></sh>
                Not surprising given that we haven't written the code yet.
            </p>
            <p>
                The fix...
<c><![CDATA[
int split_words(char *sentence) {
    int i, count = 1;
    for (i = 0; i < strlen(sentence); i++) {
        if (sentence[i] == ' ') {<strong>
            sentence[i] = '\0';</strong>
            count++;
        }
    }
    return count;
}
]]></c>
                ...reveals our previous hack...
<sh><![CDATA[
Running "main"...
Failure!: words_tests -> word_count_returned_from_split ->
        [2] should match [4] at [words_test.c] line [8]
Completed "main": 1 pass, 1 failure, 0 exceptions.
]]></sh>
                Our earlier test now fails, because we have affected
                the <code>strlen()</code> call in our loop.
                Moving the length calculation out of the loop...
<c><![CDATA[
int split_words(char *sentence) {
    int i, count = 1, <strong>length = strlen(sentence)</strong>;
    for (i = 0; <strong>i < length</strong>; i++) {
        ...
    }
    return count;
}
]]></c>
                ...restores order...
<sh>
Running "main"...
Completed "main": 2 passes, 0 failures, 0 exceptions.
</sh>
                It's nice to keep the code under control while we are
                actually writing it, rather than debugging later when things
                are more complicated.
            </p>
            <p>
                That was pretty straight forward.
                Let's do something more interesting.
            </p>
        </section>
        <section name="mock" title="What are mock functions?">
            <p>
                The next example is more realistic.
                Still in our <em>words.h</em> file, we want to write
                a function that invokes a callback on each word in a
                sentence.
                Something like...
<c><![CDATA[
void act_on_word(const char *word, void *memo) { ... }<strong>
words("This is a sentence", &act_on_word, &memo);</strong>
]]></c>
                Here the <code>memo</code> pointer is just some accumulated
                data that the <code>act_on_word()</code> callback is working with.
                Other people will write the <code>act_on_word()</code> function
                and probably many other functions like it.
                The callback is actually a flex point, and not of interest
                right now.
            </p>
            <p>
                The function under test is the <code>words()</code>
                function and we want to make sure it walks the sentence
                correctly, dispatching individual words as it goes.
                How to test this?
            </p>
            <p>
                Let's start with a one word sentence.
                In this case we would expect the callback to be invoked
                once with the only word, right?
                Here is the test for that...
<c><![CDATA[
...
#include <stdlib.h>
...<strong>
void mocked_callback(const char *word, void *memo) {
    mock(word, memo);
}

void single_word_sentence_invokes_callback_once() {
    expect(mocked_callback, want_string(word, "Word"), want(memo, NULL));
    words("Word", &mocked_callback, NULL);
}</strong>

TestSuite *words_tests() {
    TestSuite *suite = create_test_suite();
    ...
    add_test(suite, <strong>single_word_sentence_invokes_callback_once</strong>);
    return suite;
}
]]></c>
                What is the funny looking <code>mock()</code> function?
            </p>
            <p>
                A mock is basically a programmable object.
                In C objects are limited to functions, so this is a mock function.
                The macro <code>mock()</code> compares the incoming parameters with
                any expected values and dispatches messages to the test suite if
                there is a mismatch.
                It also returns any values that have been preprogrammed in the test.
            </p>
            <p>
                The test function is <code>single_word_sentence_invokes_callback_once()</code>.
                Using the <code>expect()</code> macro it programs the mock function
                to expect a single call.
                That call will have parameters <code><![CDATA["Word"]]></code> and
                <code>NULL</code>.
                If they don't match later, we will get a test failure.
            </p>
            <p>
                Only the test method, not the mock callback, is added to the test
                suite.
            </p>
            <p>
                For a successful compile and link, the <em>words.h</em> file must now
                look like...
<c><![CDATA[
int split_words(char *sentence);<strong>
void words(const char *sentence, void (*walker)(const char *, void *), void *memo);</strong>
]]></c>
                ...and the <em>words.c</em> file should have the stub...
<c><![CDATA[<strong>
void words(const char *sentence, void (*walker)(const char *, void *), void *memo) {
}</strong>
]]></c>
                This gives us the expected failing tests...
<sh><![CDATA[
Running "main"...
Failure!: words_tests -> single_word_sentence_invokes_callback_once ->
        Call was not made to function [mocked_callback] at [words_test.c] line [25]
Completed "main": 2 passes, 1 failure, 0 exceptions.
]]></sh>
                Cgreen reports that the callback was never invoked.
                We can easily get the test to pass by filling out the
                implementation with...
<c><![CDATA[
void words(const char *sentence, void (*walker)(const char *, void *), void *memo) {
    <strong>(*walker)(sentence, memo);</strong>
}
]]></c>
                That is, we just invoke it once with the whole string.
                This is a temporary measure to get us moving.
                Now everything should pass, although it's not much of a test yet.
            </p>
            <p>
                That was all pretty conventional, but let's tackle the trickier
                case of actually splitting the sentence.
                Here is the test function we will add to <em>words_test.c</em>...
<c><![CDATA[
void phrase_invokes_callback_for_each_word() {<strong>
    expect(mocked_callback, want_string(word, "Birds"));
    expect(mocked_callback, want_string(word, "of"));
    expect(mocked_callback, want_string(word, "a"));
    expect(mocked_callback, want_string(word, "feather"));</strong>
    words(<strong>"Birds of a feather"</strong>, &mocked_callback, NULL);
}
]]></c>
                Each call is expected in sequence.
                Any failures, or left over calls, or extra calls, and we
                get failures.
                We can see all this when we run the tests...
<sh><![CDATA[
Running "main"...
Failure!: words_tests -> phrase_invokes_callback_for_each_word ->
        Wanted [Birds], but got [Birds of a feather] in function [mocked_callback] parameter [word] at [words_test.c] line [30]
Failure!: words_tests -> phrase_invokes_callback_for_each_word ->
        Call was not made to function [mocked_callback] at [words_test.c] line [31]
Failure!: words_tests -> phrase_invokes_callback_for_each_word ->
        Call was not made to function [mocked_callback] at [words_test.c] line [32]
Failure!: words_tests -> phrase_invokes_callback_for_each_word ->
        Call was not made to function [mocked_callback] at [words_test.c] line [33]
Completed "main": 4 passes, 4 failures, 0 exceptions.
]]></sh>
                The first failure tells the story.
                Our little <code>words()</code> function called the mock callback
                with the entire sentence.
                This makes sense, because that was the hack to get to the next test.
            </p>
            <p>
                Although not relevant to this guide, I cannot resist getting these
                tests to pass.
                Besides, we get to use the function we created earlier...
<c><![CDATA[
void words(const char *sentence, void (*walker)(const char *, void *), void *memo) {<strong>
    char *words = strdup(sentence);
    int word_count = split_words(words);
    char *word = words;
    while (word_count-- > 0) {
        (*walker)(word, memo);
        word = word + strlen(word) + 1;
    }
    free(words);</strong>
}
]]></c>
                And with some work we are rewarded with...
<sh><![CDATA[
Running "main"...
Completed "main": 8 passes, 0 failures, 0 exceptions.
]]></sh>
                More work than I like to admit as it took me three goes to get this right.
                I firstly
                forgot the <code>+ 1</code> added on to <code>strlen()</code>,
                then forgot to swap <code>sentence</code> for
                <code>word</code> in the <code>(*walker)()</code> call,
                and finally third time lucky.
                Of course running the tests each time made these mistakes
                very obvious.
                It's taken me far longer to write these paragraphs than
                it has to write the code.
            </p>
            <p>
                <a href="http://sourceforge.net/projects/cgreen/"><img src="http://sourceforge.net/sflogo.php?group_id=130951&amp;type=5" width="210" height="62" border="0" alt="SourceForge.net Logo"/></a>
            </p>
        </section>
    </content>
    <internal>
        <link>
            What is the <a href="#what">Cgreen unit tester</a>?
        </link>
        <link>
            <a href="#install">Installing Cgreen</a> and testing the installation.
        </link>
        <link>
            <a href="#tdd">Test driven development example</a> with Cgreen in 5 minutes.
        </link>
        <link>
            Interaction testing with <a href="#mock">mock functions</a>.
        </link>
    </internal>
    <external>
        <link>
            The <a href="http://sourceforge.net/projects/cgreen">Cgreen SourceForge page</a>.
        </link>
        <link>
            Unit testing was popularised by <a href="http://extremeprogramming.org/">eXtreme Programming</a>.
        </link>
        <link>
            Cgreen is heavily influenced by the <a href="http://check.sourceforge.net/">Check</a> unit tester.
        </link>
    </external>
    <meta>
        <keywords>
            unit testing, test-first, test first, code quality, automate unit testing,
            automated testing, c programming, c tools, c unit tests, unit testing in c,
            check unit tester, mock objects, mocking functions, mocks in c, test coverage,
            tdd in C, c regression testing, cunit, cppunit, c unit testing frameworks,
            open source, open source framework, gnu licence, lgpl, free software, code quality,
            test harness
        </keywords>
    </meta>
</page>