= Userspace unit testing with PCUT =

PCUT - plain C unit testing - is (still somewhat experimental) framework/library that ought to simplify writing unit tests in C. Its main advantage is simple usage and integration with HelenOS.

PCUT itself is a standalone project with [https://github.com/vhotspur/pcut/wiki its own wiki]. This page provides mostly information specific for HelenOS (at least for now).


== Building and running PCUT tests

The PCUT tests are built by default but are not included in the final image unless explicitly enabled. To enable them, turn on the `Include userspace unit tests (PCUT)` option during HelenOS configuration.

The tests then reside in the `test/` directory, named `test-<component>` where `<component>` may refer to a standalone application or a library. It is possible to run them separately by launching individual binaries or run them all with the following command:
{{{
batch /test/run_all
}}}

This batch script also copies the result to `/data/web`, thus making them accessible by simply pointing your browser to [http://localhost:8080/test.html /test.html] (assuming you started the HelenOS web server).

The tests output their results in a [http://testanything.org/ Test-Anything-Protocol] format that is easy to understand, below is an example from successful run of `test-libc`:

{{{
1..11
#> Starting suite sprintf.
ok 1 no_formatting
ok 2 string_plain
ok 3 string_dynamic_width
ok 4 string_dynamic_width_align_left
ok 5 string_pad
ok 6 string_pad_but_cut
ok 7 char_basic
ok 8 int_various_padding
ok 9 int_negative_various_padding
ok 10 long_negative_various_padding
ok 11 int_as_hex
#> Finished suite sprintf (failed 0 of 11).
}}}


== Writing your own tests ==

The test sources are typically stored in a `test/` subdirectory of the application/library they are testing. If you want to extend already existing test case or add a new test case, open an existing file with the tests and add it there. The file may look like this (example taken from `bdsh`):

{{{#!c

/* ... */

static tokenizer_t tokenizer;
static token_t tokens[MAX_TOKENS];

/*
 * Implementation of
 * void prepare(const char *input, size_t expected_token_count)
 * is omitted.
 */

#define ASSERT_TOKEN(index, token_type, token_text) \
	do { \
		PCUT_ASSERT_INT_EQUALS(token_type, tokens[index].type); \
		PCUT_ASSERT_STR_EQUALS(token_text, tokens[index].text); \
	} while (0)



PCUT_TEST_SUITE(tokenizer);

PCUT_TEST_AFTER {
	/* Destroy the tokenizer. */
	tok_fini(&tokenizer);
}


PCUT_TEST(empty_input) {
	prepare("", 0);
}

PCUT_TEST(only_spaces) {
	prepare("   ", 1);

	ASSERT_TOKEN(0, TOKTYPE_SPACE, "   ");
}

PCUT_TEST(two_text_tokens) {
	prepare("alpha  bravo", 3);

	ASSERT_TOKEN(0, TOKTYPE_TEXT, "alpha");
	ASSERT_TOKEN(1, TOKTYPE_SPACE, "  ");
	ASSERT_TOKEN(2, TOKTYPE_TEXT, "bravo");
}

PCUT_MAIN()
}}}

Individual test cases are enclosed in `PCUT_TEST(test_name)`, available asserts are [https://github.com/vhotspur/pcut/wiki/Asserts listed here]. You might also want to read how to [https://github.com/vhotspur/pcut/wiki/Suites create test suites] that may share a [https://github.com/vhotspur/pcut/wiki/Suites#set-up-and-tear-down-routines set-up and tear-down code]. It is also possible to split [https://github.com/vhotspur/pcut/wiki/MultipleSources the tests into more files].

== Adding tests to previously untested code ==

It is recommended to put the test sources under `test/` directory to separate them from the tested code.

Add sources with the tests to the `TEST_SOURCES` variable. If your are testing a library, the test executable will be automatically linked with it. For an application (or server), you need to add all the necessary source files by yourself (it is not possible to add all of them automatically because PCUT creates its own `main()` function that would collide with the `main()` of the application).

Add path to the test to the `RD_TESTS` variable in `boot/Makefile.common`.

Basically, look how it is done for existing tests (`libc`, `libposix`, `liburi` or `bdsh`) until this how-to is improved.