Unit tests

Special framework was created for Phoenix unit tests.

The following variables should be defined in makefile for a particular unit test:

• [M] TEST_NAME – symbolic test name without spaces.
• [O] TEST_DESC – short description of the test.
• [M] TEST_SRCS – all product source files which should be compiled for this test. These files do not include source files of the test itself (test sources are searched automatically in the same directory where the makefile is located).
• [O] TEST_CXX_FLAGS – additional compiler flags.
• [O] TEST_DEFS – macros to define by ”-D” compiler options.

Source files with test cases definitions should include <phoenix_ut.h> header file. This header file is written in such a way that it does not need any additional third parties header files (e.g. standard library headers) which could cause conflicts with compilation units being tested. It also does not use any external types other than compiler built-in types. So it makes this framework very suitable for unit testing embedded solutions such as Phoenix code.

Tests writing is as simple as possible:

UT_TEST("Some test case name")
{
    // This will generate failure if someValue is not equal to anotherValue
    UT(someValue) == UT(anotherValue);
 
    if (somethingWrong) {
        // Failure can be reported explicitly
        UT_FAIL("Something went wrong");
    }
 
    UT(somePointer) != UT_NULL;
    !UT(someValueOrPointer);
}
UT_TEST_END

And that's all! Use just these several macros to describe all your test cases. 'UT' macro wraps all values in special classes which have various operators defined. If operator result is false then assertion failure is raised.

Here is an example of test source file:

#include <phoenix_ut.h>
 
UT_TEST("Stringifying boolean values")
{
    int a = 237;
    short b = 42;
    UT(a) > UT(b);
    UT(a) == UT(b);
}
UT_TEST_END
 
UT_TEST("Stringifying integer values")
{
    char s1[] = "some string";
    const char *s2 = s1;
    const char *s3 = "some string";
 
    /* Force pointers comparison, do not compare strings - should succeed. */
    UT_CPTR(s2) != UT_CPTR(s3);
    /* Compare strings - should fail. */
    UT(s2) != UT(s3);
}
UT_TEST_END

and corresponding Makefile:

TEST_NAME = OTextStream
TEST_DESC = Output text stream
 
TEST_SRCS = $(PHOENIX_ROOT)/lib/common/OTextStream.cpp \
	$(PHOENIX_ROOT)/lib/common/CommonLib.cpp
 
include $(PHOENIX_ROOT)/make/unit_test.mak

And this is output produced by this test:

========= Phoenix unit testing framework =========
Test suite: Output text stream
==== Running test 'Stringifying boolean values' (1 of 2) ====
(defined at test.cpp:14)

Assertion failed: a == b
Value: a [237] (defined at test.cpp:19)
Value: b [42] (defined at test.cpp:19)
Test FAILED
Values checked: 4
Asserts executed: 2
==== Running test 'Stringifying integer values' (2 of 2) ====
(defined at test.cpp:23)

Assertion failed: s2 != s3
Value: s2 [some string] (defined at test.cpp:32)
Value: s3 [some string] (defined at test.cpp:32)
Test FAILED
Values checked: 4
Asserts executed: 2
======== Testing complete ========
0 of 2 tests passed
Total values checked: 8
Total asserts executed: 4

The framework is able to generate stubs automatically. It searches for undefined symbols and creates a source which defines these symbols as functions. If such function will be called the fault will be produced – there is an assumption that all REQUIRED stubs are defined explicitly in test source files. It is assumed that all the rest undefined symbols should never be called (or otherwise test creator did not plan the test execution perfectly enough) and are required only to satisfy the linker. Here is an example of fault produced if the stub is called:

==== Running test 'Stringifying boolean values' (1 of 2) ====
(defined at test.cpp:14)

Fault occurred: Autogenerated stub for 'A<long>::A(long)' called
(referenced from '/home/vagran/projects/phoenix/source/phoenix/unit_tests/common/OTextStream/build/DEBUG/OTextStream.o')
Value: Autogenerated stub for 'A<long>::A(long)' called
(referenced from '/home/vagran/projects/phoenix/source/phoenix/unit_tests/common/OTextStream/build/DEBUG/OTextStream.o') (defined at /home/vagran/projects/phoenix/source/phoenix/unit_tests/common/OTextStream/build/DEBUG/auto_stabs.cpp:16)
Test FAILED
Values checked: 0
Asserts executed: 0