Cgreen Unit Test for C language
===============================
Marcus Baker <marcus@lastcraft.com>
João Henrique F. de Freitas <joaohf@gmail.com>
:Author Initials: MB JHF

Cgreen Quickstart Guide
-----------------------

[[X01]]
What is Cgreen?
~~~~~~~~~~~~~~~

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 http://www.gnu.org/licenses/lgpl.html[LGPL]

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.

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.

The feature list is:

- Fully composable test suites
- 'setup()' and 'teardown()' for tests and test suites.
- Each test runs in it's own process.
- An isolated test can be run in a single process for debugging.
- Ability to mock functions.
- The reporting mechanism can be easily extended.
        
This tool is for C programming, not C++.

[[X06]]
Installing Cgreen
~~~~~~~~~~~~~~~~~

There are two ways to install Cgreen in your system.   
      
The first is to use the RPM or DEB package provide by Cgreen Team and you cant fetch it at
http://cgreen.sourceforge.net[Cgreen website project]. Do the download and install in your
system using the normal procedures to your system. 

The second way is indicated for developers and advanced users. Basically this consist in fetch
the sources of the project and compile them. For this is necessary the http://www.cmake.org[CMake]
which is abuild system. It is a prerequisite. 

When you have the CMake tool, the steps are:

-----------------------------------------
tar -zxpvf cgreen.tar.gz
mkdir cgreen-build
cd cgreen-build
cmake ../cgreen
make
make test    
make install
-----------------------------------------

This technical is called 'build	 out of source'. It compiling and install Cgreen
outside of sources directory. These help the overall files organization.    

Is possible too use the +Makefile+. This file is used to compile
and test Cgreen without the need of CMake tool. However it does not contain the rules
to install in your system.

Both methods will create within the directory +cgreen+ a unix library called 
+libcgreen.so+ which can be used in conjunction with the
+cgreen.h+ header file to compile test code. The created library
is installed in the system, by default in the +/usr/local/lib/+.

We'll first write a test to confirm everything is working. Let's start with a simple
test script with no tests, called +first_test.c+...

[source,c]
---------------------------------------
#include "cgreen/cgreen.h"

int main(int argc, char **argv) {
TestSuite *suite = create_test_suite();
return run_test_suite(suite, create_text_reporter());
}
---------------------------------------

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 +cgreen.h+ 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.

Building this test is, of course, trivial...

-----------------------------
gcc -c first_test.c
gcc first_test.o -lcgreen -o first_test
./first_test
-----------------------------
          
Invoking the executable should give...

-----------------------------
Running "main"...
Completed "main": 0 passes, 0 failures, 0 exceptions.
-----------------------------

All of the above rather assumes you are working in a Unix like environment,
probably with 'gcc'. The code is pretty much standard C99, so any C compiler
should work.
Cgreen should compile on all systems that support the +sys/msg.h+ messaging library.
This has been tested on Linux and Mac OSX so far, but not Windows, although that
might work too.

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...

[source,c]
-----------------------------
#include "cgreen/cgreen.h"

void this_test_should_pass() {
assert_true(1);
}

void this_test_should_fail() {
assert_true(0);
}

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());
}
-----------------------------

A test can be any function with a 'void (void)' signature. 'add_test()'
is a macro, hence there is no '&' with the function pointer.

On compiling and running, we now get the output...

-----------------------------
Running "main"...
Failure!: this_test_should_fail -> Problem at [first_test.c] line [8]
Completed "main": 1 pass, 1 failure, 0 exceptions.
-----------------------------

The 'TextReporter', created by the 'create_text_reporter()' call, is the simplest
way to output the test results. It just streams the failures as text. Currently it's
the only method supported.


[[X07]]
Five minutes doing TDD with Cgreen
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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...

[source,c]
-------------------------------
char *sentence = strdup("Just the first test");
word_count = split_words(sentence);
-------------------------------

'sentence' should now point at "Just\0the\0first\0test". Not an obviously useful
function, but we'll be using it for something more practical below.

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 'main()' runner file.
This makes it less work to add more tests.

Here is the, so far empty, test case in 'words_test.c'...

[source,c]
-------------------------------
#include "cgreen/cgreen.h"

TestSuite *words_tests() {
TestSuite *suite = create_test_suite();
return suite;
}
-------------------------------

Here is the 'all_tests.c' test runner...

[source,c]
-------------------------------
#include "cgreen/cgreen.h"

TestSuite *words_tests();

int main(int argc, char **argv) {
TestSuite *suite = create_test_suite();
add_suite(suite, words_tests());
if (argc > 1) {
  return run_single_test(suite, argv[1], create_text_reporter());
}
return run_test_suite(suite, create_text_reporter());
}
-------------------------------

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 'run_test_suite()'. While this makes
all the tests independent, the constant 'fork()ing' can make the tests difficult to debug.
To make debugging simpler, Cgreen does not fork() when only a single test is run 
by name with 'run_single_test()'.

Building this scaffolding...

-------------------------------
gcc -c words_test.c
gcc -c all_tests.c
gcc words_test.o all_tests.o -lcgreen -o all_tests
-------------------------------

...and executing the result gives the familiar...

-------------------------------
Running "main"...
Completed "main": 0 passes, 0 failures, 0 exceptions.
-------------------------------

All this scaffolding is pure overhead, but from now on adding tests will be a lot easier.

Here is a first test of 'split_words()'...

[source,c]
-------------------------------
#include "cgreen/cgreen.h";
#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);
}

TestSuite *words_tests() {
TestSuite *suite = create_test_suite();
add_test(suite, word_count_returned_from_split);
return suite;
}
-------------------------------

The 'assert_equal()' macro takes in the two values to compare. With the default
'TextReporter' the message is sent to 'STDOUT'.

To get this to compile we need to create the +words.h+ header file...

[source,c]
-------------------------------
int split_words(char *sentence);
-------------------------------

...and to get the code to link we need a stub function in 'words.c'...

[source,c]
-------------------------------
int split_words(char *sentence) {
return 0;
}
-------------------------------

A full build later...

-------------------------------
gcc -c all_tests.c
gcc -c words_test.c
gcc -c words.c
gcc all_tests.o words_test.o words.o -lcgreen -o all_tests
./all_tests
-------------------------------

...and we get the more useful response...

-------------------------------
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.
-------------------------------

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.
      
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...

[source,c]
--------------------------------
#include <string.h>;

int split_words(char *sentence) {
int i, count = 1;
for (i = 0; i < strlen(sentence); i++) {
  if (sentence[i] == ' ') {
      count++;
  }
}
return count;
}
---------------------------------

There is a hidden problem here, but our tests still pass so we'll pretend we didn't notice.

Time to add another test. We want to confirm that the string is broken into separate words...

[source,c]
---------------------------------
#include "cgreen/cgreen.h"
#include "words.h"
#include <string.h>;

void word_count_returned_from_split() { ... }

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); 
}

TestSuite *words_tests() {
TestSuite *suite = create_test_suite();
add_test(suite, word_count_returned_from_split);
add_test(suite, spaces_should_be_converted_to_zeroes);
return suite;
}
----------------------------------

Sure enough, we get a failure...

----------------------------------
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.
----------------------------------

Not surprising given that we haven't written the code yet.

The fix...

[source,c]
----------------------------------
int split_words(char *sentence) {
int i, count = 1;
for (i = 0; i < strlen(sentence); i++) {
  if (sentence[i] == ' ') {
      sentence[i] = '\0';
      count++;
  }
}
return count;
}
----------------------------------

...reveals our previous hack...

----------------------------------
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.
----------------------------------

Our earlier test now fails, because we have affected the 'strlen()' call in our loop.
Moving the length calculation out of the loop...

[source,c]
----------------------------------
int split_words(char *sentence) {
int i, count = 1, length = strlen(sentence);
for (i = 0; i < length; i++) {
  ...
}
return count;
}
----------------------------------

...restores order...
		  
----------------------------------
Running "main"...
Completed "main": 2 passes, 0 failures, 0 exceptions.
----------------------------------

It's nice to keep the code under control while we are actually writing it, rather
than debugging later when things are more complicated.

That was pretty straight forward. Let's do something more interesting.

[[X08]]
What are mock functions?

The next example is more realistic. Still in our +words.h+ file, we want to write
a function that invokes a callback on each word in a sentence. Something like...

[source,c]
----------------------------------
void act_on_word(const char *word, void *memo) { ... }
words("This is a sentence", &act_on_word, &memo);
----------------------------------

Here the 'memo' pointer is just some accumulated data that the 'act_on_word()'
callback is working with. Other people will write the 'act_on_word()' function
and probably many other functions like it. The callback is actually a flex point,
and not of interest right now.

The function under test is the 'words()' function and we want to make sure it walks
the sentence correctly, dispatching individual words as it goes. How to test this?

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...

[source,c]
---------------------------------
...
#include <stdlib.h>
...
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);
}

TestSuite *words_tests() {
TestSuite *suite = create_test_suite();
...
add_test(suite, single_word_sentence_invokes_callback_once);
return suite;
}
---------------------------------

What is the funny looking 'mock()' function?

A mock is basically a programmable object. In C objects are limited to functions,
so this is a mock function. The macro 'mock()' 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.
 
The test function is 'single_word_sentence_invokes_callback_once()'. Using the 'expect()'
macro it programs the mock function to expect a single call. That call will have
parameters "Word" and 'NULL'. If they don't match later, we will get a test failure.

Only the test method, not the mock callback, is added to the test suite.

For a successful compile and link, the +words.h+ file must now look like...

[source,c]
----------------------------
int split_words(char *sentence);
void words(const char *sentence, void (*walker)(const char *, void *), void *memo);
----------------------------

...and the +words.c+ file should have the stub...

[source,c]
----------------------------
void words(const char *sentence, void (*walker)(const char *, void *), void *memo) {
}
----------------------------

This gives us the expected failing tests...

----------------------------
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.
----------------------------

Cgreen reports that the callback was never invoked. We can easily get the test to
pass by filling out the implementation with...

[source,c]
----------------------------
void words(const char *sentence, void (*walker)(const char *, void *), void *memo) {
(*walker)(sentence, memo);
}
----------------------------

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.

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 +words_test.c+...

[source,c]
----------------------------
void phrase_invokes_callback_for_each_word() {
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"));
words("Birds of a feather", &mocked_callback, NULL);
}
----------------------------

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...

----------------------------
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.
-----------------------------

The first failure tells the story. Our little 'words()' function called the mock
callback with the entire sentence. This makes sense, because that was the hack to
get to the next test.

Although not relevant to this guide, I cannot resist getting these tests to pass.
Besides, we get to use the function we created earlier...

[source,c]
-----------------------------
void words(const char *sentence, void (*walker)(const char *, void *), void *memo) {
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);
}
------------------------------

And with some work we are rewarded with...

------------------------------
Running "main"...
Completed "main": 8 passes, 0 failures, 0 exceptions.
------------------------------

More work than I like to admit as it took me three goes to get this right. I firstly
forgot the '+ 1' added on to 'strlen()', then forgot to swap 'sentence' for 'word'
in the '(*walker)()' 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.

[[X02]]
Building Cgreen test suites
---------------------------

Cgreen is a tool for building unit tests in the C language. These are usually written
alongside the production code by the programmer to prevent bugs. Even though the test
suites are created by software developers, they are intended to be human readable C
code, as part of their function is an executable specification.
Used in this way, the test harness delivers constant quality assurance.

In other words you'll get less bugs.

[[X09]]
Writing basic tests
~~~~~~~~~~~~~~~~~~~

Cgreen tests are simply C functions with no parameters and a 'void' return value.
An example might be...

[source,c]
-----------------------------
static void strlen_of_hello_should_be_five() {
    assert_equal(strlen("Hello"), 5);
}
-----------------------------

The test function name can be anything you want. The 'assert_equal()' call is an example
of an assertion. Assertions send messages to Cgreen, which in turn outputs the results.

Here are the standard assertions...

|=========================================================
|Assertion |Description
|assert_true(boolean) |Passes if boolean evaluates true
|assert_false(boolean) |Fails if boolean evaluates true
|assert_equal(first, second) |Passes if 'first == second'
|assert_not_equal(first, second) |Passes if 'first != second'
|assert_string_equal(char *, char *) |Uses 'strcmp()' and passes if the strings are equal
|assert_string_not_equal(char *, char *) |Uses 'strcmp()' and fails if the strings are equal

|=========================================================

The boolean assertion macros accept an 'int' value. The equality assertions accept anything
that can be cast to 'intptr_t' and simply perform an '==' operation. The string comparisons
are slightly different in that they use the '<string.h>' library function 'strcmp()'.
If 'assert_equal()' is used on 'char *' pointers then the pointers have to point at the same string.

Each assertion has a default message comparing the two values. If you want to substitute
your own failure messages, then you must use the '*_with_message()' counterparts...

|=========================================================
|Assertion
|assert_true_with_message(boolean, message, ...)
|assert_false_with_message(boolean, message, ...)
|assert_equal_with_message(first, second, message, ...)
|assert_not_equal_with_message(first, second, message, ...)
|assert_string_equal_with_message(char *, char *, message, ...)
|assert_string_not_equal_with_message(char *, char *, message, ...)

|=========================================================

All these assertions have an additional 'char *' message parameter, which is the message
you wished to display on failure. If this is set to 'NULL', then the default message 
is shown instead. The most useful assertion from this group is 'assert_true_with_message()'
as you can use that to create your own assertion functions with your own messages.

Actually the assertion macros have variable argument lists. The failure message acts 
like the template in 'printf()'. We could change the test above to be...

[source,c]
-----------------------------
static void strlen_of_hello_should_be_five() {
    const char *greeting = "Hello";
    int length = strlen(greeting);
    assert_equal_with_message(length, 5, "[%s] should be 5, but was %d", greeting, length);
}
-----------------------------

A slightly more user friendly message when things go wrong. 

For the test above to work there needs to be a running test suite. We can create one
expecially for this test like so...

[source,c]
-----------------------------
TestSuite *our_tests() {
    TestSuite *suite = create_test_suite();
    add_test(suite, strlen_of_hello_should_be_five);
    return suite;
}
-----------------------------

In case you have spotted that 'strlen_of_hello_should_be_five()' should have an ampersand
in front of it, 'add_test()' is a macro. The '&' is added automatically.

To run the test suite, we call 'run_test_suite()' on it. This function cleans up the 
test suite after running it, so we can just write...

[source,c]
-----------------------------
run_test_suite(our_tests(), create_text_reporter());
-----------------------------

The results of assertions are ultimately delivered as passes and failures to a collection
of callbacks defined in a 'TestReporter' structure. The only predefined one in Cgreen 
is the 'TextReporter' that delivers messages in plain text.

A full test script now looks like...

[source,c]
-----------------------------
#include "cgreen/cgreen.h"
#include <string.h>

static void strlen_of_hello_should_be_five() {
    assert_equal(strlen("Hello"), 5);
}

TestSuite *our_tests() {
    TestSuite *suite = create_test_suite();
    add_test(suite, strlen_of_hello_should_be_five);
    return suite;
}

int main(int argc, char **argv) {
    return run_test_suite(our_tests(), create_text_reporter());
}
-----------------------------

The return value of 'run_test_suite()' is a Unix exit code.

Compliling and running gives...

-----------------------------
gcc -c strlen_test.c
gcc strlen_test.o -lcgreen -o strlen_test
./strlen_test
Running "main"...
Completed "main": 1 pass, 0 failures, 0 exceptions.
-----------------------------

The test messages are only shown on failure. If we break our test...

[source,c]
-----------------------------
static void strlen_of_hello_should_be_five() {
    assert_equal(strlen("Hiya", 5);
}
-----------------------------

...we'll get the helpful message...

-----------------------------
Running "main"...
Failure!: strlen_of_hello_should_be_five ->
        [5] shold be [4] at [strlen_test.c] line [6]
Completed "main": 0 passes, 1 failure, 0 exceptions.
-----------------------------
                
Cgreen appends the location of the test failure to our error string.


Once we have a basic test scaffold up, it's pretty easy to add more tests. Adding a test
of 'strlen()' with an empty string for example...

[source,c]
-----------------------------
...
static void strlen_of_empty_string_should_be_zero() {
    assert_equal(strlen("\0"), 0);
}

TestSuite *our_tests() {
    TestSuite *suite = create_test_suite();
    add_test(suite, strlen_of_hello_should_be_five);
    add_test(suite, strlen_of_empty_string_should_be_zero);
    return suite;
}
...
-----------------------------

And so on.

[[X10]]
Set up and tear down
~~~~~~~~~~~~~~~~~~~~

It's common for test suites to have a lot of duplicate code, especially when setting
up similar tests. Take this database code for example...

[source,c]
-----------------------------
#include "cgreen/cgreen.h"
#include <stdlib.h>
#include <mysql/mysql.h>
#include "person.h"

static void create_schema() {
    MYSQL *connection = mysql_init(NULL);
    mysql_real_connect(connection, "localhost", "me", "secret", "test", 0, NULL, 0);
    mysql_query(connection, "create table people (name, varchar(255) unique)");
    mysql_close(connection);
}

static void drop_schema() {
    MYSQL *connection = mysql_init(NULL);
    mysql_real_connect(connection, "localhost", "me", "secret", "test", 0, NULL, 0);
    mysql_query(connection, "drop table people");
    mysql_close(connection);
}

static void can_add_person_to_database() {
    create_schema();
    Person *person = create_person();
    set_person_name(person, "Fred");
    save_person(person);
    Person *found = find_person_by_name("Fred");
    assert_string_equal(get_person_name(person), "Fred");
    drop_schema();
}

static void cannot_add_duplicate_person() {
    create_schema();
    Person *person = create_person();
    set_person_name(person, "Fred");
    assert_true(save_person(person));
    Person *duplicate = create_person();
    set_person_name(duplicate, "Fred");
    assert_false(save_person(duplicate));
    drop_schema();
}

TestSuite *person_tests() {
    TestSuite *suite = create_test_suite();
    add_test(suite, can_add_person_to_database);
    add_test(suite, cannot_add_duplicate_person);
    return suite;
}

int main(int argc, char **argv) {
    return run_test_suite(person_tests(), create_text_reporter());
}
--------------------------

We have already factored out the duplicate code into it's own functions 'create_scheme()'
and 'drop_schema()', so things are not so bad. At least not yet. What happens when we
get dozens of tests? For a test subject as compicated as a database
http://www.martinfowler.com/eaaCatalog/activeRecord.html[ActiveRecord], having dozens
 f tests is very likely.

We can get Cgreen to do some of the work for us by declaring these methods as 'setup()' and
'teardown()' functions in the test suite.
 
Here is the new version...

[source,c]
-----------------------------
...
static void create_schema() { ... }

static void drop_schema() { ... }

static void can_add_person_to_database() {
    Person *person = create_person();
    set_person_name(person, "Fred");
    save_person(person);
    Person *found = find_person_by_name("Fred");
    assert_string_equal(get_person_name(person), "Fred");
}

static void cannot_add_duplicate_person() {
    Person *person = create_person();
    set_person_name(person, "Fred");
    assert_true(save_person(person));
    Person *duplicate = create_person();
    set_person_name(duplicate, "Fred");
    assert_false(save_person(duplicate));
}

TestSuite *person_tests() {
    TestSuite *suite = create_test_suite();
    setup(suite, create_schema);
    teardown(suite, drop_schema);
    add_test(suite, can_add_person_to_database);
    add_test(suite, cannot_add_duplicate_person);
    return suite;
}
...
---------------------------

With this new arrangement Cgreen runs the 'create_schema()' function before each test,
and the 'drop_schema()' function after each test. This saves some repetitive typing and
reduces the chance of accidents. It also makes the tests more focused.

The reason we try so hard to strip everything out of the test functions is that that
the test suite acts as documentation. In our +person.h+ example we can easily see that
'Person' has some kind of name property, and that this value must be unique. For the tests
to act like a readable specification we have to remove as much mechanical clutter as we can.

A couple of details. Currently only one 'setup()' and 'teardown()' may be added to each
'TestSuite'. Also the 'teardown()' function may not be run if the test crashes, causing
some test interference. This brings us nicely onto the next section...

[[X11]]
Each test in it's own process
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Consider this test method...

[source,c]
-----------------------------
void will_seg_fault() {
    int *p = NULL;
    (*p)++;
}
-----------------------------

Crashes are not something you would normally want to have in a test run. Not least 
because it will stop you receiving the very test output you need to tackle the problem.

To prevent segmentation faults and other problems bringing down the test suites, Cgreen
runs every test in it's own process.

Just before the 'setup()' call, Cgreen 'fork()''s. The main process wait's for the test
to complete normally or die. This includes the 'teardown()'. If the test process dies, 
an exception is reported and the main test process carries on.

For example...

[source,c]
-----------------------------
#include "cgreen/cgreen.h"
#include <stdlib.h>

static void will_seg_fault() {
    int *p = NULL;
    (*p)++;
}

int main(int argc, char **argv) {
    TestSuite *suite = create_test_suite();
    add_test(suite, will_seg_fault);
    run_test_suite(suite, create_text_reporter());
}
-----------------------------


When built and run, this gives...

-----------------------------
Running "main"...
Exception!: will_seg_fault -> Test "will_seg_fault" failed to complete
Completed "main": 0 passes, 0 failures, 1 exception.
-----------------------------

The obvious thing to do now is to fire up the debugger. Unfortunately, the constant
'fork()''ing of Cgreen can be an extra complication too many when debugging. It's enough
of a problem to find the bug.

To get around this, and also to allow the running of one test at a time, Cgreen has the
'run_single_test()' function. The signatures of the two run methods are...

- 'int run_test_suite(TestSuite *suite, TestReporter *reporter);'
- 'int run_single_test(TestSuite *suite, char *test, TestReporter *reporter);'

The extra parameter of 'run_single_test()', the 'test' string, is the name of the test to select.
This could be any test, even in nested test suites (see below). Here is how we would use 
it to debug our crashing test...

[source,c]
-----------------------------
int main(int argc, char **argv) {
    TestSuite *suite = create_test_suite();
    add_test(suite, will_seg_fault);
    run_single_test(suite, "will_seg_fault", create_text_reporter());
}
-----------------------------

When run in this way, Cgreen will not 'fork()'.

This deals with the segmentation fault case, but what about a process that fails to complete
by getting stuck in a loop?

Well, Cgreen will wait forever too. Using the C signal handlers, we can place a time limit on the
process by sending it an interrupt. To save us writing this ourselves, Cgreen includes the
'die_in()' function to help us out.

Here is an example of time limiting a test...

[source,c]
-----------------------------
...
static void will_seg_fault() { ... }

static void this_would_stall() {
    die_in(1);
    while(0 == 0) { }
}

int main(int argc, char **argv) {
    TestSuite *suite = create_test_suite();
    add_test(suite, will_seg_fault);
    add_test(suite, this_would_stall);
    run_test_suite(suite, create_text_reporter());
}
---------------------------
                
When executed, the code will slow for a second, and then finish with...

---------------------------
Running "main"...
Exception!: will_seg_fault -> Test "will_seg_fault" failed to complete
Exception!: will_stall -> Test "this_would_stall" failed to complete
Completed "main": 0 passes, 0 failures, 2 exceptions.
---------------------------

Note that you see the test results as they come in. Cgreen streams the results as they
happen, making it easier to figure out where the test suite has problems.

Of course, if you want to set a general time limit on all your tests, then you can add
a 'die_in()' to a 'setup()' function. Cgreen will then apply the limit to all of them.

[[X12]]
Building composite test suites
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
            
The 'TestSuite' is a composite structure.
This means test suites can be added to test suites, building
a tree structure that will be executed in order.

Let's combine the 'strlen()' tests with the
'Person' tests above.
Firstly we need to remove the 'main()' calls.
E.g...

[source,c]
-----------------------------
#include "cgreen/cgreen.h"
#include <string.h>

static void strlen_of_hello_should_be_five() { ... }
static void strlen_of_empty_string_should_be_zero() { ... }

TestSuite *our_tests() {
    TestSuite *suite = create_test_suite();
    add_test(suite, strlen_of_hello_should_be_five);
    add_test(suite, strlen_of_empty_string_should_be_zero);
    return suite;
}
----------------------------

Then we can write a small runner script with a new
'main()' function...

[source,c]
-----------------------------
#include "strlen_tests.c"
#include "person_tests.c"

TestSuite *our_tests();
TestSuite *person_tests();

int main(int argc, char **argv) {
    TestSuite *suite = create_test_suite();
    add_suite(suite, our_tests());
    add_suite(suite, person_tests());
    if (argc > 1) {
        return run_single_test(suite, argv[1], create_text_reporter());
    }
    return run_test_suite(suite, create_text_reporter());
}
-----------------------

It's usually easier to place the 'TestSuite'
prototypes in the runner
scripts, rather than have lot's of header files.
This is the same reasoning that let us drop the prototypes
for the test functions in the actual test scripts.
We can get away with this, because the tests are more about
documentation than encapsulation.
                         
It's sometimes handy to be able to run just a single test
from the command line, so we added a simple 'if'
block to take the test name as an optional argument.
The entire test suite will be searched for the named
test.
This trick also saves us a recomplile when we debug.
             
            
We've placed each test suite in it's own file, but that
is not necessary.
We could build several test suites in the same file, even
nesting them.
We can even add mixtures of test functions and test suites
to the same parent test suite.
Loops will give trouble, however.
             
            
If we do place several suites in the same file, then
all the suites will be named the same
in the breadcrumb trail in the test message.
They will all be named after the function the create call sits in.
If you want to get around this, or you just like to name
your test suites, you can use 'create_named_test_suite()'
instead of 'create_test_suite()'.
This takes a single string parameter.
In fact 'create_test_suite()' is just a macro that
inserts the '__func__' constant into
'create_named_test_suite()'.
             
            
What happens to 'setup()' and 'teardown()'
in a 'TestSuite' that contains other
'TestSuite's?


Well firstly, Cgreen does not 'fork()' when running
a suite.
It leaves it up to the child suite to 'fork()'
the individual tests.
This means that a 'setup()' and 'teardown()'
will run in the main process.
They will be run once for each child suite.


We can use this to speed up our 'Person' tests
above.
Remember we were creating a new connection and closing it
again in the fixtures.
This means opening and closing a lot of connections.
At the slight risk of some test interference, we could
reuse the connection accross tests...

[source,c]
-----------------------
...
static MYSQL *connection;

static void create_schema() {
    mysql_query(connection, "create table people (name, varchar(255) unique)");
}

static void drop_schema() {
    mysql_query(connection, "drop table people");
}

static void can_add_person_to_database() { ... }
static void cannot_add_duplicate_person() { ... }

void open_connection() {
    connection = mysql_init(NULL);
    mysql_real_connect(connection, "localhost", "me", "secret", "test", 0, NULL, 0);
}

void close_connection() {
    mysql_close(connection);
}

TestSuite *person_tests() {
    TestSuite *suite = create_test_suite();
    setup(suite, create_schema);
    teardown(suite, drop_schema);
    add_test(suite, can_add_person_to_database);
    add_test(suite, cannot_add_duplicate_person);

    TestSuite *fixture = create_named_test_suite("Mysql fixture");
    add_suite(fixture, suite);
    setup(fixture, open_connection);
    teardown(fixture, close_connection);
    return fixture;
}
-----------------------

The trick here is creating a test suite as a wrapper
whose sole purpose to wrap the main test suite in
the fixture.
This is our 'fixture' pointer.
This code is a little confusing, because we have two sets of
fixtures in the same test script.


We have the MySQL connection fixture.
This is runs 'open_connection()' and
'close_connection()' just
once at the beginning and end of the person tests.
This is because the 'suite' pointer is the
only member of 'fixture'.


We also have the schema fixture, the 'create_schema()'
and 'drop_schema()', which is run before
and after every test.
Those are still attached to the inner 'suite'.


In the real world we would probably place the connection
fixture in it's own file...

[source,c]
-----------------------
static MYSQL *connection;

MYSQL *get_connection() {
    return connection;
}

static void open_connection() {
    connection = mysql_init(NULL);
    mysql_real_connect(connection, "localhost", "me", "secret", "test", 0, NULL, 0);
}

static void close_connection() {
    mysql_close(connection);
}

TestSuite *connection_fixture(TestSuite *suite) {
    TestSuite *fixture = create_named_test_suite("Mysql fixture");
    add_suite(fixture, suite);
    setup(fixture, open_connection);
    teardown(fixture, close_connection);
    return fixture;
}
-----------------------

This allows the reuse of common fixtures across projects.
             
[[X03]]
Mocking functions with Cgreen
-----------------------------
        
When testing you want certainty above all else.
Random events destroy confidence in your test suite
and force needless extra runs &quot;to be sure&quot;.
A good test places the subject under test into a
tightly controlled environment.
A test chamber if you like.
This makes the tests fast, repeatable and reliable.


To create a test chamber for testing code, we have
to control any outgoing calls from the code under test.
We won't believe our test failure if our code is making
calls to the internet for example.
The internet can fail all by itself.
Not only do we not have total control, but it means
we have to get dependent components
working before we can test the higher level code.
This makes it difficult to code top down.


The solution to this dilemma is to write stub code for
the components whilst the higher level code is written.
This pollutes the code base with temporary code, and
the test isolation disappears when the system is eventually
fleshed out.


The ideal is to have minimal stubs written for each
individual test.
Cgreen encourages this approach by making such tests
easier to write.
         
[[X13]]
The problem with streams
~~~~~~~~~~~~~~~~~~~~~~~~
            
How do we test this code...?

[source,c]
-----------------------
char *read_paragraph(int (*read)(void *), void *stream) {
    int buffer_size = 0, length = 0;
    char *buffer = NULL;
    int ch;
    while ((ch = (*read)(stream)) != EOF) {
        if (++length > buffer_size) {
            buffer_size += 100;
            buffer = realloc(buffer, buffer_size + 1);
        }
        if ((buffer[length] = ch) == '\n') {
            break;
        }
    }
    return buffer;
}
-----------------------

This is a fairly generic stream filter that turns
the incoming characters into C string paragraphs.
Each call creates one paragraph, returning a pointer
to it or returning 'NULL' if there is no paragraph.
The paragraph has memory allocated to it and the
stream is advanced ready for the next call.
That's quite a bit of functionality, and there
are plenty of nasty boundary conditions.
I really want this code tested before I deploy it.


The problem is the stream dependency.
We could use a real stream, but that will cause all sorts of
headaches.
It makes the test of our paragraph formatter dependent
on a working stream.
It means we have to write the stream first, bottom up coding
rather than top down.
It means we will have to simulate stream failures - not easy.
It will also mean setting up external resources.
This is more work, will run slower, and could lead
to spurious test failures.


By contrast we could write a simulation of the stream for each
test, called a "server stub".


For example, when the stream is empty nothing should happen.
We hopefully get 'NULL' from 'read_paragraph'
when the stream is exhausted.
That is, it just returns a steady stream of 'EOF's.

[source,c]
-----------------------
static int empty_stream(void *stream) {
    return EOF;
}

static void reading_lines_from_empty_stream_gives_null() {
    assert_equal(read_paragraph(&empty_stream, NULL), NULL);
}

TestSuite *stream_tests() {
    TestSuite *suite = create_test_suite();
    add_test(suite, reading_lines_from_empty_stream_gives_null);
    return suite;
}
-----------------------

Our simulation is easy here, because our fake stream returns only
one value.
Things are harder when the function result changes from
call to call as a real stream would.
Simulating this would mean messing around with static variables and counters
that are reset for each test.
And of course, we will be writing quite a few stubs.
Often a different one for each test.
That's a lot of clutter.


Cgreen handles this clutter for us
by letting us write a single programmable function
for all our tests.
             
[[X14]] 
Record and playback
~~~~~~~~~~~~~~~~~~~
            
We can redo our example by creating a 'stub_stream()' function
(any name will do)...

[source,c]
-----------------------
static int stub_stream(void *stream) {
    return (int)mock();
}
-----------------------

Hardly longer that our trivial server stub above,
it is just a macro to generate a return value,
but we can reuse this in test after test.


For our simple example above we just tell it to always return
'EOF'...

[source,c]
-----------------------
static int stub_stream(void *stream) {
    return (int)mock();
}

static void reading_lines_from_empty_stream_gives_null() {
    always_return(stub_stream, EOF);
    assert_equal(read_paragraph(stub_stream, NULL), NULL);
}
-----------------------

The 'always_return()' macro takes as arguments the
function name and the return value.
We have told 'stub_stream()' to always return
'EOF' when called.


Let's see if our production code actually works...

-----------------------
Running "main"...
Completed "main": 1 pass, 0 failures, 0 exceptions.
-----------------------

So far, so good.
On to the next test.


If we want to test a one character line, we have to send
the terminating 'EOF' or '"\n"'
as well as the single character.
Otherwise our code will loop forever, giving an infinite
line of that character.


Here is how we can do this...

[source,c]
-----------------------
static void one_character_stream_gives_one_character_line() {
    will_return(stub_stream, 'a');
    will_return(stub_stream, EOF);
    char *line = read_paragraph(&stub_stream, NULL);
    assert_string_equal(line, "a");
    free(line);
}
-----------------------

Unlike the 'always_return()' instruction, 'will_return()'
sets just a single return value.
It acts like a record and playback model.
Successive instructions map out the return sequence that will be
given back once the test proper starts.


We'll add this test to the suite and run it...

-----------------------
Running "main"...
Failure!: stream_tests -> one_character_stream_gives_one_character_line ->
        [] should match [a] at [stream_test.c] line [19]
Completed "main": 1 pass, 1 failure, 0 exceptions.
-----------------------

Oops. Our code under test doesn't work.
Already we need a fix...

[source,c]
-----------------------
char *read_paragraph(int (*read)(void *), void *stream) {
    int buffer_size = 0, length = 0;
    char *buffer = NULL;
    int ch;
    while ((ch = (*read)(stream)) != EOF) {
        if (++length > buffer_size) {
            buffer_size += 100;
            buffer = realloc(buffer, buffer_size + 1);
        }
        if ((buffer[length - 1] = ch) == '\n') {
            break;
        }
    }
    return buffer;
}
-----------------------

After which everything is fine...

-----------------------
Running "main"...
Completed "main": 2 passes, 0 failures, 0 exceptions.
-----------------------
             
            
How do the Cgreen stubs work?
The 'will_return()' calls build up a static list of
return values which are cleared between tests.
The 'mock()' macro captures the
'__func__' property.
It uses these to look up entries in the return list, and also to
generate more helpful messages.


We can crank out our tests quite quickly now...

[source,c]
-----------------------
static void one_word_stream_gives_one_word_line() {
    will_return(stub_stream, 't');
    will_return(stub_stream, 'h');
    will_return(stub_stream, 'e');
    always_return(stub_stream, EOF);
    assert_string_equal(read_paragraph(&stub_stream, NULL), "the");
}
-----------------------

I've been a bit naughty.
As each test runs in it's own process, I haven't bothered
to free the pointers to the paragraphs.
I've just let the operating system do it.
Purists may want to add the extra clean up code.


I've also used 'always_return()' for the last instruction.
Withou this, if the stub is given an instruction is does
not expect, it will throw a test failure.
This is overly restrictive, as our 'read_paragraph()'
function could quite legitimately call the stream after it had
run off of the end.
OK, that would be odd behaviour, but that's not what we are testing here.
If we were, it would be placed in a test of it's own.
The 'always_return()' call tells <emphasis>Cgreen to keep
going after the first three letters, allowing extra calls.
             
            
As we build more tests, they start to look like a specification
of the behaviour...

[source,c]
-----------------------
static void drops_line_ending_from_word_and_stops() {
    will_return(stub_stream, 't');
    will_return(stub_stream, 'h');
    will_return(stub_stream, 'e');
    will_return(stub_stream, '\n');
    assert_string_equal(read_paragraph(&stub_stream, NULL), "the");
}
-----------------------

...and just for luck...

[source,c]
-----------------------
static void single_line_ending_gives_empty_line() {
    will_return(stub_stream, '\n');
    assert_string_equal(read_paragraph(&stub_stream, NULL), "");
}
-----------------------


This time we musn't use 'always_return()'.
We want to leave the stream where it is, ready for the next
call to 'read_paragraph()'.
If we call the stream beyond the line ending, we want to fail.
             
            
It turns out that we are failing anyway...

-----------------------
Running "main"...
Failure!: stream_tests -> drops_line_ending_from_word_and_stops -> [the
] should match [the] at [stream_test.c] line [36]
Failure!: stream_tests -> single_line_ending_gives_empty_line -> [
] should match [] at [stream_test.c] line [41]
Completed "main": 3 passes, 2 failures, 0 exceptions.
-----------------------

Clearly we are passing through the line ending.
Another fix later...

[source,c]
-----------------------
char *read_paragraph(int (*read)(void *), void *stream) {
    int buffer_size = 0, length = 0;
    char *buffer = NULL;
    int ch;
    while ((ch = (*read)(stream)) != EOF) {
        if (++length > buffer_size) {
            buffer_size += 100;
            buffer = realloc(buffer, buffer_size + 1);
        }
        if ((buffer[length - 1] = ch) == '\n') {
            buffer[--length] = '\0';
            break;
        }
        buffer[length] = '\0';
    }
    return buffer;
}
-----------------------

And we are passing again...

-----------------------
Running "main"...
Completed "main": 5 passes, 0 failures, 0 exceptions.
-----------------------
             
            
There are no limits to the number of stubbed methods within a
test, only that two stubs cannot have the same name.
So this will cause problems...

[source,c]
-----------------------
static int stub_stream(void *stream) {
    return (int)mock();
}

static void bad_test() {
    will_return(stub_stream, 'a');
    do_stuff(&stub_stream, &stub_stream);
}
-----------------------

It will be necessary to have two stubs to make this test behave...

[source,c]
-----------------------
static int first_stream(void *stream) {
    return (int)mock();
}

static int second_stream(void *stream) {
    return (int)mock();
}

static void good_test() {
    will_return(first_stream, 'a');
    will_return(second_stream, 'a');
    do_stuff(&first_stream, &second_stream);
}
-----------------------

We now have a way of writing fast, clear tests with no
external dependencies.
The information flow is still one way though, from stub to the
code under test.
When our code calls complex procedures, we won't want to pick
apart the effects to infer what happened.
That's too much like detective work.
And why should we?
We just want to know that we dispatched the correct information
down the line.


Things get more interesting when we thing of
the traffic going the other way, from code to stub.
This gets us into the same territory as mock objects.
             
[[X15]]
Setting expectations on mock functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
            
To swap the traffic flow, we'll look at an outgoing example instead.
Here is the prewritten production code...

[source,c]
-----------------------
void by_paragraph(int (*read)(void *), void *in, void (*write)(void *, char *), void *out) {
    while (1) {
        char *line = read_paragraph(read, in);
        if (line == NULL) {
            return;
        }
        (*write)(out, line);
        free(line);
    }
}
-----------------------

This is the start of a formatter utility.
Later filters will probably break the paragaphs up into justified text,
but right now that is all abstracted behind the
'void write(void *, char *)' interface.
Our current interests are: does it loop through the paragraphs, and does
it crash?


We could test correct paragraph formation by writing a stub
that collects the paragraphs into a 'struct'.
We could then pick apart that 'struct' and test
each piece with assertions.
This approach is extremely clumsy in C.
The language is just not suited to building and tearing down
complex edifices, never mind navigating them with assertions.
We would badly clutter our tests.


Instead we'll test the output as soon as possible, right in
the called function...

[source,c]
-----------------------
...
void expect_one_letter_paragraph(char *paragraph, void *stream) {
    assert_string_equal(paragraph, "a", NULL);
}

void one_character_is_made_into_a_one_letter_paragraph() {
    by_paragraph(
            &one_character_stream,
            NULL,
            &expect_one_letter_paragraph,
            NULL);
}
...
-----------------------

By placing the assertions into the mocked function, we
keep the tests minimal.
The catch with this method is that we are back to writing
individual functions for each test.
We have the same problem as we had with hand coded stubs.


Again, <emphasis>Cgreen has a way to automate this.
Here is the rewritten test...

[source,c]
-----------------------
static int reader(void *stream) {
    return (int)mock(stream);
}

static void writer(void *stream, char *paragraph) {
    mock(stream, paragraph);
}

void one_character_is_made_into_a_one_letter_paragraph() {
    will_return(reader, 'a');
    always_return(reader, EOF);
    expect(writer, want_string(paragraph, "a"));
    by_paragraph(&reader, NULL, &writer, NULL);
}
-----------------------

Where are the assertions?


Unlike our earlier stub, 'reader()' can now check it's
parameters.
In object oriented circles, an object that checks it's
parameters as well as simulating behaviour is called a
mock object.
By analogy 'reader()' is a mock function, or
mock callback.
             
            
Using the 'expect' macro, we have stated that
'writer()' will be called just once.
That call must have the string '"a"' for the
paragraph parameter.
If this parameter does not match, the mock function will
issue a failure straight to the test suite.
This is what saves us writing a lot of assertions.
             
            
Here is the full list of instructions that can be sent to the mocks...

|=========================================
|Macro| Parameters
|'will_return(function, result)'| Returns result once only, but successive calls 
will be replayed in order. Generates a failure when called too many times.
|'always_return(function, result)'| Returns result repeatedly.
|'expect(function, arguments...)'| Sets up an expectation on each argument. If there is a mismatch,
 or a call is made without an expectation, a failure is generated.
|'always_expect(function, arguments...)'| Must receive exactly these arguments from now on.
|'expect_never(function)'| This function must not be called or a failure is generated.
|'will_respond(function, result, arguments...)'| Combines 'will_return()' and 'expect()'.
|'always_respond(function, result, arguments...)'| Combines 'always_return()' and 'always_expect()'
|=========================================

The 'expect_never()' macro is slightly different.
It's only task is to confirm that a method was never run.


The 'will_respond()' macro combines the 'will_return()'
and the 'expect()' calls into one call, as does 'always_respond'.


Each parameter can be tested with a constraint.
Two constraints are available:
'want(parameter, expected)' for integers and pointers, and
'want_string(parameter, expected)' does a string comparison.


It's about time we actually ran our test...

-----------------------
Running "main"...
Completed "main": 6 passes, 0 failures, 0 exceptions.
-----------------------

Confident that a single character works, we can further
specify the behaviour.
Firstly an input sequence...

[source,c]
-----------------------
static void no_line_endings_makes_one_paragraph() {
    will_return(reader, 'a');
    will_return(reader, ' ');
    will_return(reader, 'b');
    will_return(reader, ' ');
    will_return(reader, 'c');
    always_return(reader, EOF);
    expect(writer, want_string(paragraph, "a b c"));
    by_paragraph(&reader, NULL, &writer, NULL);
}
-----------------------

A more intelligent programmer than me would place all
these calls in a loop.
Next, checking an output sequence...

[source,c]
-----------------------
static void line_endings_generate_separate_paragraphs() {
    will_return(reader, 'a');
    will_return(reader, '\n');
    will_return(reader, 'b');
    will_return(reader, '\n');
    will_return(reader, 'c');
    always_return(reader, EOF);
    expect(writer, want_string(paragraph, "a"));
    expect(writer, want_string(paragraph, "b"));
    expect(writer, want_string(paragraph, "c"));
    by_paragraph(&reader, NULL, &writer, NULL);
}
-----------------------

Like the 'will_return()' stubs above, the
'expect()' calls follow a record and playback model.
Each one tests a successive call.
This sequence confirms that we get '"a"',
'"b"' and '"c"' in
order.


Then we'll make sure the correct stream pointers are passed to
the correct functions.
This is a more realistic parameter check...

[source,c]
-----------------------
static void resources_are_paired_with_the_functions() {
    will_respond(reader, 'a', want(stream, 1));
    always_respond(reader, EOF, want(stream, 1));
    expect(writer, want(stream, 2));
    by_paragraph(&reader, (void *)1, &writer, (void *)2);
}
-----------------------

And finally we'll specify that the writer is not called if
there is no paragraph.

[source,c]
-----------------------
static void empty_paragraphs_are_ignored() {
    will_return(reader, '\n');
    always_return(reader, EOF);
    expect_never(writer);
    by_paragraph(&reader, NULL, &writer, NULL);
}
-----------------------

This last test is our undoing...

-----------------------
Running "main"...
Failure!: stream_tests -> empty_paragraphs_are_ignored ->
        Unexpected call to function [writer] at [stream_test.c] line [96]
Completed "main": 14 passes, 1 failure, 0 exceptions.
-----------------------

Obviously blank lines are still being dispatched to the
'writer()'.
Once this is pointed out, the fix is obvious...

[source,c]
-----------------------
void by_paragraph(int (*read)(void *), void *in, void (*write)(void *, char *), void *out) {
    while (1) {
        char *line = read_paragraph(read, in);
        if ((line == NULL) || (strlen(line) == 0)) {
            return;
        }
        (*write)(out, line);
        free(line);
    }
}
-----------------------

Tests with 'expect_never()' can be very effective
at uncovering subtle bugs.

-----------------------
Running "main"...
Completed "main": 14 passes, 0 failures, 0 exceptions.
-----------------------

All done.
             
[[X04]]
Changing Cgreen Reporting
-------------------------

[[X16]]
Replacing the reporter
~~~~~~~~~~~~~~~~~~~~~~
            
In every test suite so far, we have run the tests
with this line...

[source,c]
-----------------------
return run_test_suite(our_tests(), create_text_reporter());
-----------------------

We can change the reporting mechanism just by changing this
method.
Here is the code for 'create_text_reporter()'...

[source,c]
-----------------------
TestReporter *create_text_reporter() {
    TestReporter *reporter = create_reporter();
    reporter->start = &text_reporter_start;
    reporter->finish = &text_reporter_finish;
    reporter->show_fail = &show_fail;
    reporter->show_incomplete = &show_incomplete;
    return reporter;
}
-----------------------

The 'TestReporter' structure contains function
pointers that control the reporting.
When called from 'create_reporter()' constructor, these
pointers are set up with functions that display nothing.
The text reporter code replaces these with something more
dramatic, and then returns a pointer to this new object.
Thus the 'create_text_reporter()' function effectively
extends the object from 'create_reporter()'.
             
            
The text reporter only outputs content at the start of the first test,
at the end of the test run to display the results, when a failure
occours, and when a test fails to complete.
A quick look at the +text_reporter.c+ file in +Cgreen+
reveals that the overrides just output a message and
chain to the versions in +reporter.h+.


To change the reporting mechanism ourselves, we just have to know a little
about the methods in the 'TestReporter' structure.
             
[[X17]]
The TestReporter structure

The Cgreen 'TestReporter' is a pseudo class that looks
something like...

[source,c]
-----------------------
typedef struct _TestReporter TestReporter;
struct _TestReporter {
    void (*destroy)(TestReporter *);
    void (*start)(TestReporter *, const char *);
    void (*finish)(TestReporter *, const char *);
    void (*show_pass)(TestReporter *, const char *, int, const char *, va_list);
    void (*show_fail)(TestReporter *, const char *, int, const char *, va_list);
    void (*show_incomplete)(TestReporter *, const char *);
    void (*assert_true)(TestReporter *, const char *, int, int, const char *, ...);
    int passes;
    int failures;
    int exceptions;
    void *breadcrumb;
    int ipc;
    void *memo;
};
-----------------------

The first block are the methods that can be overridden.

[horizontal]
'void (*destroy)(TestReporter *)':: This is the destructor for the default 
structure. If this is overridden, then the overriding function must call 
'destroy_reporter(TestReporter *reporter)' to finish the clean up. 

'void (*start)(TestReporter *, const char *)':: The first of the callbacks. At 
the start of each test suite Cgreen will call this method on the reporter with 
the name of the suite being entered. The default version keeps track of the stack 
of tests in the 'breadcrumb' pointer of 'TestReporter'. If you make use of the 
breadcrumb functions, as the defaults do, then you will need to call 
'reporter_start()' to keep the book keeping in sync.
 
'void (*finish)(TestReporter *, const char *)':: The counterpart to the 
'(*start)()' call called on leaving the test suite. It needs to be chained to the 
'reporter_finish()' to keep track of the breadcrumb book keeping. The text 
reporter uses the state of the breadcrumb to decide if it is ending teh top level 
test. If so, it prints the familiar summary of passes and fails.

'void (*show_pass)(TestReporter *, const char *, int, const char *, va_list)':: This method is initially empty, so there is no need to chain the call to any 
other function. Besides the pointer to the reporter structure, Cgreen also passes 
the file name of the test, the line number of failed assertion, the message to 
show and any additional parameters to substitute into the message. The message 
comes in as 'printf()' style format string, and so the variable argument list 
should match the substitutions. 

'void (*show_fail)(TestReporter *, const char *, int, const char *, va_list)':: The partner of 'show_pass()', and the one you'll likely overload first. 

'void (*show_incomplete)(TestReporter *, const char *)':: When a test fails to 
complete, this is the handler that is called. As it's an unexpected outcome, no 
message is received, but we do get the name of the test. The text reporter 
combines this with the breadcrumb to produce the exception report.

'void (*assert_true)(TestReporter *, const char *, int, int, const char *, ...)':: This is not normally overridden and is really internal. It is the raw 
entry point for the test messages from the test suite. By default it dispatches 
teh call to either 'show_pass()' or 'show_fail()'.


The second block is simply resources and book keeping that the reporter
can use to liven up the messages...

[horizontal]
'passes':: The number of passes so far.
'failures'::  The number of failures generated so far.
'exceptions':: The number of test functions that have failed to complete so far. 
'breadcrumb':: This is a pointer to the list of test names in the stack.
				
The 'breadcrumb' pointer is different and needs a
little explanation.
Basically it is a stack, analagous to the breadcrumb trail you
see on websites.
Everytime the 'start()' handler is invoked, the
name is placed in this stack.
When the 'finish()' message handler is invoked, a
name is popped off.


There are a bunch of utility functions in +cgreen/breadcrumb.h+
that can read the state of this stack.
Most useful are 'get_current_from_breadcrumb()' which
takes the breadcrumb pointer and returns the curent test name,
and 'get_breadcrumb_depth()' which gives the current
depth of the stack.
A depth of zero means that the test run has finished.


If you need to traverse all the names in the breadcrumb,
then you can call 'walk_breadcrumb()'.
Here is the full signature...

[source,c]
-----------------------
void walk_breadcrumb(Breadcrumb *breadcrumb, void (*walker)(const char *, void *), void *memo);
-----------------------

The 'void (*walker)(const char *, void *)' is a callback
that will be passed the name of the test suite for each
level of nesting.
It is also poassed the 'memo' pointer that was
passed to the 'walk_breadcrumb()' call.
You can use this pointer for anything you want, as
all <emphasis>Cgreen does is pass it from call to call.
This is so aggregate information can be kept track of whilst
still being reentrant.


The last parts of the 'TestReporter' structure are...

[horizontal]
'ipc':: This is an internal structure for handling the messaging between reporter
and test suite. You shouldn't touch this.
'memo':: By contrast, this is a spare pointer for your own expansion.
             
[[X18]]
An example XML reporter
~~~~~~~~~~~~~~~~~~~~~~~
            
Let's make things real with an example.
Suppose we want to send the output from <emphasis>Cgreen in XML format,
say for storing in a repository or for sending across the network.
             
            
Suppose also that we have come up with the following format...

[source,xml]
-----------------------
<?xml?>
<test name="Top Level">
    <test name="A Group">
        <test name="a_test_that_passes">
        </test>
        <test name="a_test_that_fails">
            <fail>
                <message>A failure</message>
                <location file="test_as_xml.c" line="8"/>
            </fail>
        </test>
    </test>
</test>
-----------------------

In other words a simple nesting of tests with only failures
encoded.
The absence of failure is a pass.


Here is a test script, +test_in_xml.c+ that we can use to construct the
above output...

[source,c]
-----------------------
#include "cgreen/cgreen.h"

void a_test_that_passes() {
    assert_true(1);
}

void a_test_that_fails() {
    assert_true_with_message(0, "A failure");
}

TestSuite *create_test_group() {
    TestSuite *suite = create_named_test_suite("A Group");
    add_test(suite, a_test_that_passes);
    add_test(suite, a_test_that_fails);
    return suite;
}

int main(int argc, char **argv) {
    TestSuite *suite = create_named_test_suite("Top Level");
    add_suite(suite, create_test_group());
    return run_test_suite(suite, create_text_reporter());
}
-----------------------

The text reporter is used just to confirm that everything
is working.
So far it is.

-----------------------
Running "Top Level"...
Failure!: A Group -> a_test_that_fails -> A failure at [test_as_xml.c] line [8]
Completed "Top Level": 1 pass, 1 failure, 0 exceptions.
-----------------------
             
            
Our first move is to switch the reporter from text, to our
not yet written XML version...

[source,c]
-----------------------
#include "cgreen/cgreen.h
#include "xml_reporter.h"

...

int main(int argc, char **argv) {
    TestSuite *suite = create_named_test_suite("Top Level");
    add_suite(suite, create_test_group());
    return run_test_suite(suite, create_xml_reporter());
}
-----------------------

We'll start the ball rolling with the +xml_reporter.h+
header file...

[source,c]
-----------------------
#ifndef _XML_REPORTER_HEADER_
#define _XML_REPORTER_HEADER_

#include "cgreen/reporter.h"

TestReporter *create_xml_reporter();

#endif
-----------------------

...and the simplest possible reporter in +reporter.c+.

[source,c]
-----------------------
#include "xml_reporter.h"
#include "cgreen/reporter.h"

TestReporter *create_xml_reporter() {
    TestReporter *reporter = create_reporter();
    return reporter;
}
-----------------------

One that outputs nothing.

-----------------------
gcc -c test_as_xml.c
gcc -c xml_reporter.c
gcc xml_reporter.o test_as_xml.o -lcgreen -o xml
./xml
-----------------------

Yep, nothing.


Let's add the outer test tags first, so that we can see Cgreen navigating the test suite...

-----------------------
#include "xml_reporter.h"
#include "cgreen/reporter.h"
#include <stdio.h>

static void xml_reporter_start(TestReporter *reporter, const char *name);
static void xml_reporter_finish(TestReporter *reporter, const char *name);

TestReporter *create_xml_reporter() {
    TestReporter *reporter = create_reporter();
    reporter->start = &xml_reporter_start;
    reporter->finish = &xml_reporter_finish;
    return reporter;
}

static void xml_reporter_start(TestReporter *reporter, const char *name) {
    printf("<test name=\"%s\">\n", name);
    reporter_start(reporter, name);
}

static void xml_reporter_finish(TestReporter *reporter, const char *name) {
    reporter_finish(reporter, name);
    printf("</test>\n");
}
-----------------------

Although chaining to the underlying 'reporter_start()'
and 'reporter_finish()' functions is optional, I want to
make use of some of the facilities later.


Our output meanwhile, is making it's first tentative steps...

[source,xml]
-----------------------
<test name="Top Level">
<test name="A Group">
<test name="a_test_that_passes">
</test>
<test name="a_test_that_fails">
</test>
</test>
</test>
-----------------------

We don't want a passing message, so the 'show_fail()' function is all we
need...

[source,c]
-----------------------
...
static void xml_show_fail(TestReporter *reporter, const char *file, int line, const char *message, va_list arguments);

TestReporter *create_xml_reporter() {
    TestReporter *reporter = create_reporter();
    reporter->start = &xml_reporter_start;
    reporter->finish = &xml_reporter_finish;
    reporter->show_fail = &xml_show_fail;
    return reporter;
}

...

static void xml_show_fail(TestReporter *reporter, const char *file, int line, const char *message, va_list arguments) {
    printf("<fail>\n");
    printf("\t<message>");
    vprintf(message, arguments);
    printf("]]></message>\n");
    printf("\t<location file=\"%s\" line=\"%d\"/>\n", file, line);
    printf("</fail>\n");
}
-----------------------

We have to use 'vprintf()' to handle the variable argument
list passed to us.
This will probably mean including the +stdarg.h+ header
as well as +stdio.h+.
             
            
This gets us pretty close to what we want...
			
[source,xml]				
-----------------------
<test name="Top Level">
<test name="A Group">
<test name="a_test_that_passes">
</test>
<test name="a_test_that_fails">
<fail>
    <message>A failure]]></message>
    <location file="test_as_xml.c" line="9"/></fail>
</test>
</test>
</test>
-----------------------

For completeness we should add a tag for an incomplete test.
We'll output this as a failure, athough we don't get a location this
time...

[source,c]
-----------------------
static void xml_show_incomplete(TestReporter *reporter, const char *name) {
    printf("<fail>\n");
    printf("\t<message>Failed to complete]]></message>\n");
    printf("</fail>\n");
}
-----------------------

All that's left then is the XML declaration and the thorny issue of
indenting.
Although the indenting is not strictly necessary, it would make the
output a lot more readable.
             
            
The test depth is kept track of for us with the 'breadcrumb'
object in the 'TestReporter' structure.
We'll add an 'indent()' function that outputs the
correct number of tabs...

[source,c]
-----------------------
static indent(TestReporter *reporter) {
    int depth = get_breadcrumb_depth((Breadcrumb *)reporter->breadcrumb);
    while (depth-- > 0) {
        printf("\t");
    }
}
-----------------------

The 'get_breadcrumb_depth()' function just gives the
current test depth.
As that is just the number of tabs to output, the implementation
is trivial.
             
            
We can then use this function in the rest of the code.
Here is the complete listing...

[source,c]
-----------------------
#include "xml_reporter.h"
#include "cgreen/reporter.h"
#include "cgreen/breadcrumb.h"
#include <stdio.h>
#include <stdarg.h>

static indent(TestReporter *reporter);
static void xml_reporter_start(TestReporter *reporter, const char *name);
static void xml_reporter_finish(TestReporter *reporter, const char *name);
static void xml_show_fail(TestReporter *reporter, const char *file, int line, const char *message, va_list arguments);
static void xml_show_incomplete(TestReporter *reporter, const char *name);

TestReporter *create_xml_reporter() {
    TestReporter *reporter = create_reporter();
    reporter->start = &xml_reporter_start;
    reporter->finish = &xml_reporter_finish;
    reporter->show_fail = &xml_show_fail;
    reporter->show_incomplete = &xml_show_incomplete;
    return reporter;
}

static indent(TestReporter *reporter) {
    int depth = get_breadcrumb_depth((Breadcrumb *)reporter->breadcrumb);
    while (depth-- > 0) {
        printf("\t");
    }
}

static void xml_reporter_start(TestReporter *reporter, const char *name) {
    if (get_breadcrumb_depth((Breadcrumb *)reporter->breadcrumb) == 0) {
        printf("<?xml?>\n");
    }
    indent(reporter);
    printf("<test name=\"%s\">\n", name);
    reporter_start(reporter, name);
}

static void xml_reporter_finish(TestReporter *reporter, const char *name) {
    reporter_finish(reporter, name);
    indent(reporter);
    printf("</test>\n");
}

static void xml_show_fail(TestReporter *reporter, const char *file, int line, const char *message, va_list arguments) {
    indent(reporter);
    printf("<fail>\n");
    indent(reporter);
    printf("\t<message>");
    vprintf(message, arguments);
    printf("]]></message>\n");
    indent(reporter);
    printf("\t<location file=\"%s\" line=\"%d\"/>\n", file, line);
    indent(reporter);
    printf("</fail>\n");
}

static void xml_show_incomplete(TestReporter *reporter, const char *name) {
    indent(reporter);
    printf("<fail>\n");
    indent(reporter);
    printf("\t<message>Failed to complete]]></message>\n");
    indent(reporter);
    printf("</fail>\n");
}
-----------------------

And finally the desired output...

-----------------------
<?xml?>
<test name="Top Level">
    <test name="A Group">
        <test name="a_test_that_passes">
        </test>
        <test name="a_test_that_fails">
            <fail>
                <message>A failure]]></message>
                <location file="test_as_xml.c" line="9"/>
            </fail>
        </test>
    </test>
</test>
-----------------------

Job done.
                         
Possible other extensions include reporters that write to <emphasis>syslog,
talk to IDE plug-ins, paint pretty printed documents or just return a boolean
for monitoring purposes.
             
[[X05]]
Automaticaly tests collector	
----------------------------

[[X19]]
The collector tool
~~~~~~~~~~~~~~~~~~
            
When we want to add a new test, we open the test script and create a new
void function. So we add the name of the function inside of TestSuite.
				
In summary each new test added we should added inside of TestSuite too.                


The collector tool change this
boring behaviour. The idea is to save work of add every tests written inside
of 'TestSuite'. Basically each test is to be declared with the macro
Ensure in which is automatically inserted
inside of 'TestSuite'.
                                                          
[[X20]]
Example
~~~~~~~
            
To use the collector tool we need to modify the definition of each functions.
Before we used:

[source,c]
-----------------------
void one_should_assert_char_equal_to_one() {
	char x = 1;
	char y = 1;
    assert_equal(x, y);
}
-----------------------

Now we need to rewrite to:

[source,c]				
-----------------------
Ensure one_should_assert_char_equal_to_one() {
	char x = 1;
	char y = 1;
    assert_equal(x, y);
}
-----------------------
                
For each writen test, we must declared like Ensure type. 
It is a C macro and tell to collector that this test should be put inside the TestSuite.                
 

In the TestSuite we don't more need to write the testes with compound the TestSuite. Just let
like:

[source,c]
-----------------------                
TestSuite *assertion_tests() {
    TestSuite *suite = create_test_suite();
    add_tests();
    return suite;
}                
-----------------------     
                           
Assuming that our test script is the file +assertion_tests.c+, 
running the 'collector' we have:
				
-----------------------                
./collector assertion_tests.c
-----------------------

The finally result in test script is:

[source,c]
-----------------------
Ensure one_should_assert_char_equal_to_one() {
	char x = 1;
	char y = 1;
    assert_equal(x, y);
}

TestSuite *assertion_tests() {
    TestSuite *suite = create_test_suite(&one_should_assert_char_equal_to_one);
    add_tests();
    return suite;
}
-----------------------
           
          
The tool read all script, do the necessary substituitions and write to the
original file.
So just add a new test and run the collector tool to adjust automatically the
TestSuite.
           
[[X21]]
GNU Free Documentation License
------------------------------


    Version 1.1, March 2000

    
      Copyright (C) 2000  Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
    
    0. PREAMBLE

    The purpose of this License is to make a manual, textbook,
    or other written document "free" in the sense of freedom: to
    assure everyone the effective freedom to copy and redistribute it,
    with or without modifying it, either commercially or
    noncommercially.  Secondarily, this License preserves for the
    author and publisher a way to get credit for their work, while not
    being considered responsible for modifications made by
    others.

    This License is a kind of "copyleft", which means that
    derivative works of the document must themselves be free in the
    same sense.  It complements the GNU General Public License, which
    is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals
    for free software, because free software needs free documentation:
    a free program should come with manuals providing the same
    freedoms that the software does.  But this License is not limited
    to software manuals; it can be used for any textual work,
    regardless of subject matter or whether it is published as a
    printed book.  We recommend this License principally for works
    whose purpose is instruction or reference.

    1. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work that
    contains a notice placed by the copyright holder saying it can be
    distributed under the terms of this License.  The "Document",
    below, refers to any such manual or work.  Any member of the
    public is a licensee, and is addressed as "you".

    A "Modified Version" of the Document means any work
    containing the Document or a portion of it, either copied
    verbatim, or with modifications and/or translated into another
    language.

    A "Secondary Section" is a named appendix or a front-matter
    section of the Document that deals exclusively with the
    relationship of the publishers or authors of the Document to the
    Document's overall subject (or to related matters) and contains
    nothing that could fall directly within that overall subject.
    (For example, if the Document is in part a textbook of
    mathematics, a Secondary Section may not explain any mathematics.)
    The relationship could be a matter of historical connection with
    the subject or with related matters, or of legal, commercial,
    philosophical, ethical or political position regarding
    them.

    The "Invariant Sections" are certain Secondary Sections
    whose titles are designated, as being those of Invariant Sections,
    in the notice that says that the Document is released under this
    License.

    The "Cover Texts" are certain short passages of text that
    are listed, as Front-Cover Texts or Back-Cover Texts, in the
    notice that says that the Document is released under this
    License.

    A "Transparent" copy of the Document means a
    machine-readable copy, represented in a format whose specification
    is available to the general public, whose contents can be viewed
    and edited directly and straightforwardly with generic text
    editors or (for images composed of pixels) generic paint programs
    or (for drawings) some widely available drawing editor, and that
    is suitable for input to text formatters or for automatic
    translation to a variety of formats suitable for input to text
    formatters.  A copy made in an otherwise Transparent file format
    whose markup has been designed to thwart or discourage subsequent
    modification by readers is not Transparent.  A copy that is not
    "Transparent" is called "Opaque".

    Examples of suitable formats for Transparent copies include
    plain ASCII without markup, Texinfo input format, LaTeX input
    format, SGML or XML using a publicly available DTD, and
    standard-conforming simple HTML designed for human modification.
    Opaque formats include PostScript, PDF, proprietary formats that
    can be read and edited only by proprietary word processors, SGML
    or XML for which the DTD and/or processing tools are not generally
    available, and the machine-generated HTML produced by some word
    processors for output purposes only.

    The "Title Page" means, for a printed book, the title page
    itself, plus such following pages as are needed to hold, legibly,
    the material this License requires to appear in the title page.
    For works in formats which do not have any title page as such,
    "Title Page" means the text near the most prominent appearance of
    the work's title, preceding the beginning of the body of the
    text.

    2. VERBATIM COPYING

    You may copy and distribute the Document in any medium,
    either commercially or noncommercially, provided that this
    License, the copyright notices, and the license notice saying this
    License applies to the Document are reproduced in all copies, and
    that you add no other conditions whatsoever to those of this
    License.  You may not use technical measures to obstruct or
    control the reading or further copying of the copies you make or
    distribute.  However, you may accept compensation in exchange for
    copies.  If you distribute a large enough number of copies you
    must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated
    above, and you may publicly display copies.

    3. COPYING IN QUANTITY

    If you publish printed copies of the Document numbering more
    than 100, and the Document's license notice requires Cover Texts,
    you must enclose the copies in covers that carry, clearly and
    legibly, all these Cover Texts: Front-Cover Texts on the front
    cover, and Back-Cover Texts on the back cover.  Both covers must
    also clearly and legibly identify you as the publisher of these
    copies.  The front cover must present the full title with all
    words of the title equally prominent and visible.  You may add
    other material on the covers in addition.  Copying with changes
    limited to the covers, as long as they preserve the title of the
    Document and satisfy these conditions, can be treated as verbatim
    copying in other respects.

    If the required texts for either cover are too voluminous to
    fit legibly, you should put the first ones listed (as many as fit
    reasonably) on the actual cover, and continue the rest onto
    adjacent pages.

    If you publish or distribute Opaque copies of the Document
    numbering more than 100, you must either include a
    machine-readable Transparent copy along with each Opaque copy, or
    state in or with each Opaque copy a publicly-accessible
    computer-network location containing a complete Transparent copy
    of the Document, free of added material, which the general
    network-using public has access to download anonymously at no
    charge using public-standard network protocols.  If you use the
    latter option, you must take reasonably prudent steps, when you
    begin distribution of Opaque copies in quantity, to ensure that
    this Transparent copy will remain thus accessible at the stated
    location until at least one year after the last time you
    distribute an Opaque copy (directly or through your agents or
    retailers) of that edition to the public.

    It is requested, but not required, that you contact the
    authors of the Document well before redistributing any large
    number of copies, to give them a chance to provide you with an
    updated version of the Document.

    4. MODIFICATIONS

    You may copy and distribute a Modified Version of the
    Document under the conditions of sections 2 and 3 above, provided
    that you release the Modified Version under precisely this
    License, with the Modified Version filling the role of the
    Document, thus licensing distribution and modification of the
    Modified Version to whoever possesses a copy of it.  In addition,
    you must do these things in the Modified Version:

      Use in the Title Page
      (and on the covers, if any) a title distinct from that of the
      Document, and from those of previous versions (which should, if
      there were any, be listed in the History section of the
      Document).  You may use the same title as a previous version if
      the original publisher of that version gives permission.
      

      List on the Title Page,
      as authors, one or more persons or entities responsible for
      authorship of the modifications in the Modified Version,
      together with at least five of the principal authors of the
      Document (all of its principal authors, if it has less than
      five).
      

      State on the Title page
      the name of the publisher of the Modified Version, as the
      publisher.
      

      Preserve all the
      copyright notices of the Document.
      

      Add an appropriate
      copyright notice for your modifications adjacent to the other
      copyright notices.
      

      Include, immediately
      after the copyright notices, a license notice giving the public
      permission to use the Modified Version under the terms of this
      License, in the form shown in the Addendum below.
      

      Preserve in that license
      notice the full lists of Invariant Sections and required Cover
      Texts given in the Document's license notice.
      

      Include an unaltered
      copy of this License.
      

      Preserve the section
      entitled "History", and its title, and add to it an item stating
      at least the title, year, new authors, and publisher of the
      Modified Version as given on the Title Page.  If there is no
      section entitled "History" in the Document, create one stating
      the title, year, authors, and publisher of the Document as given
      on its Title Page, then add an item describing the Modified
      Version as stated in the previous sentence.
      

      Preserve the network
      location, if any, given in the Document for public access to a
      Transparent copy of the Document, and likewise the network
      locations given in the Document for previous versions it was
      based on.  These may be placed in the "History" section.  You
      may omit a network location for a work that was published at
      least four years before the Document itself, or if the original
      publisher of the version it refers to gives permission.
      

      In any section entitled
      "Acknowledgements" or "Dedications", preserve the section's
      title, and preserve in the section all the substance and tone of
      each of the contributor acknowledgements and/or dedications
      given therein.
      

      Preserve all the
      Invariant Sections of the Document, unaltered in their text and
      in their titles.  Section numbers or the equivalent are not
      considered part of the section titles.
      

      Delete any section
      entitled "Endorsements".  Such a section may not be included in
      the Modified Version.
      

      Do not retitle any
      existing section as "Endorsements" or to conflict in title with
      any Invariant Section.
      
    
    If the Modified Version includes new front-matter sections
    or appendices that qualify as Secondary Sections and contain no
    material copied from the Document, you may at your option
    designate some or all of these sections as invariant.  To do this,
    add their titles to the list of Invariant Sections in the Modified
    Version's license notice.  These titles must be distinct from any
    other section titles.

    You may add a section entitled "Endorsements", provided it
    contains nothing but endorsements of your Modified Version by
    various parties--for example, statements of peer review or that
    the text has been approved by an organization as the authoritative
    definition of a standard.

    You may add a passage of up to five words as a Front-Cover
    Text, and a passage of up to 25 words as a Back-Cover Text, to the
    end of the list of Cover Texts in the Modified Version.  Only one
    passage of Front-Cover Text and one of Back-Cover Text may be
    added by (or through arrangements made by) any one entity.  If the
    Document already includes a cover text for the same cover,
    previously added by you or by arrangement made by the same entity
    you are acting on behalf of, you may not add another; but you may
    replace the old one, on explicit permission from the previous
    publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by
    this License give permission to use their names for publicity for
    or to assert or imply endorsement of any Modified Version.

    5. COMBINING DOCUMENTS

    You may combine the Document with other documents released
    under this License, under the terms defined in section 4 above for
    modified versions, provided that you include in the combination
    all of the Invariant Sections of all of the original documents,
    unmodified, and list them all as Invariant Sections of your
    combined work in its license notice.

    The combined work need only contain one copy of this
    License, and multiple identical Invariant Sections may be replaced
    with a single copy.  If there are multiple Invariant Sections with
    the same name but different contents, make the title of each such
    section unique by adding at the end of it, in parentheses, the
    name of the original author or publisher of that section if known,
    or else a unique number.  Make the same adjustment to the section
    titles in the list of Invariant Sections in the license notice of
    the combined work.

    In the combination, you must combine any sections entitled
    "History" in the various original documents, forming one section
    entitled "History"; likewise combine any sections entitled
    "Acknowledgements", and any sections entitled "Dedications".  You
    must delete all sections entitled "Endorsements."

    6. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and
    other documents released under this License, and replace the
    individual copies of this License in the various documents with a
    single copy that is included in the collection, provided that you
    follow the rules of this License for verbatim copying of each of
    the documents in all other respects.

    You may extract a single document from such a collection,
    and distribute it individually under this License, provided you
    insert a copy of this License into the extracted document, and
    follow this License in all other respects regarding verbatim
    copying of that document.

    7. AGGREGATION WITH INDEPENDENT WORKS
    
    A compilation of the Document or its derivatives with other
    separate and independent documents or works, in or on a volume of
    a storage or distribution medium, does not as a whole count as a
    Modified Version of the Document, provided no compilation
    copyright is claimed for the compilation.  Such a compilation is
    called an "aggregate", and this License does not apply to the
    other self-contained works thus compiled with the Document, on
    account of their being thus compiled, if they are not themselves
    derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to
    these copies of the Document, then if the Document is less than
    one quarter of the entire aggregate, the Document's Cover Texts
    may be placed on covers that surround only the Document within the
    aggregate.  Otherwise they must appear on covers around the whole
    aggregate.

    8. TRANSLATION

    Translation is considered a kind of modification, so you may
    distribute translations of the Document under the terms of section
    4.  Replacing Invariant Sections with translations requires
    special permission from their copyright holders, but you may
    include translations of some or all Invariant Sections in addition
    to the original versions of these Invariant Sections.  You may
    include a translation of this License provided that you also
    include the original English version of this License.  In case of
    a disagreement between the translation and the original English
    version of this License, the original English version will
    prevail.

    9. TERMINATION
    
    You may not copy, modify, sublicense, or distribute the
    Document except as expressly provided for under this License.  Any
    other attempt to copy, modify, sublicense or distribute the
    Document is void, and will automatically terminate your rights
    under this License.  However, parties who have received copies, or
    rights, from you under this License will not have their licenses
    terminated so long as such parties remain in full
    compliance.

    10. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised
    versions of the GNU Free Documentation License from time to time.
    Such new versions will be similar in spirit to the present
    version, but may differ in detail to address new problems or
    concerns.  See http://www.gnu.org/copyleft/.

    Each version of the License is given a distinguishing
    version number.  If the Document specifies that a particular
    numbered version of this License "or any later version" applies to
    it, you have the option of following the terms and conditions
    either of that specified version or of any later version that has
    been published (not as a draft) by the Free Software Foundation.
    If the Document does not specify a version number of this License,
    you may choose any version ever published (not as a draft) by the
    Free Software Foundation.

    How to use this License for your documents

    To use this License in a document you have written, include
    a copy of the License in the document and put the following
    copyright and license notices just after the title page:


      Copyright (c)  YEAR  YOUR NAME.
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with the Invariant Sections being LIST THEIR TITLES, with the
      Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
      A copy of the license is included in the section entitled "GNU
      Free Documentation License".


    If you have no Invariant Sections, write "with no Invariant
    Sections" instead of saying which ones are invariant.  If you have
    no Front-Cover Texts, write "no Front-Cover Texts" instead of
    "Front-Cover Texts being LIST"; likewise for Back-Cover
    Texts.

    If your document contains nontrivial examples of program
    code, we recommend releasing these examples in parallel under your
    choice of free software license, such as the GNU General Public
    License, to permit their use in free software.

