Unit Test Framework

A lightweight, easy to use, C++11 unit testing framework implemented in a single .h file.

Publicly available tutorial: https://eecs280staff.github.io/unit_test_framework/

Quickstart

Install the unit test framework by copying unit_test_framework.h into your project.

$ wget https://raw.githubusercontent.com/eecs280staff/unit_test_framework/master/unit_test_framework.h

Get the unit test example.

$ wget https://raw.githubusercontent.com/eecs280staff/unit_test_framework/my_tests.cpp

Compile and run.

$ g++ --std=c++11 my_tests.cpp -o my_tests.exe
$ ./my_tests.exe
Running test: bool_is_true
PASS
Running test: numbers_equal
PASS

*** Results ***
** Test case 'bool_is_true': PASS
** Test case 'numbers_equal': PASS
*** Summary ***
Out of 2 tests run:
0 failure(s), 0 error(s)

The example my_tests.cpp looks like this:

// File: my_tests.cpp

#include "unit_test_framework.h"

// TEST takes in one argument: the name of the test case.
// Note that the name of the test case must be a valid function name in C++.
TEST(numbers_equal) {
    int spam = 42;
    ASSERT_EQUAL(spam, 42);  // If spam != 42, this test case will fail
}

TEST(bool_is_true) {
    bool egg = true;
    ASSERT_TRUE(egg);  // If egg is not true, this test case will fail
}

// DO NOT REMOVE
// Generates a main() function that runs all of your tests.
// Note: Some versions of g++ incorrectly produce a warning about empty
// statements when using the -pedantic flag. Therefore, we will not put
// a semicolon after the TEST_MAIN() macro.
TEST_MAIN()

How to write a test case: The TEST() macro

Test cases can be declared using the special TEST() macro defined in unit_test_framework.h:

TEST(<test_name>) {
    // test case code
}

Replace <test_name> with the name of the test case. Note that <test_name> must be a valid C++ function name.

TEST(test_a_thing) {
    // test case code
}

Special Asserts

You can use any amount of these special asserts in your test cases. You can also use the special asserts in helper functions.

ASSERT_EQUAL(first, second)

• If first == second evaluates to false, the test will fail.
• first and second may be any type

ASSERT_NOT_EQUAL(first, second)

• If first != second evaluates to false, the test will fail.
• first and second may be any type

ASSERT_TRUE(bool value)

• If value is false, the test will fail.

ASSERT_FALSE(bool value)

• If value is true, the test will fail.

ASSERT_ALMOST_EQUAL(double first, double second, double precision)

• If first and second are not equal within precision, the test will fail.

ASSERT_SEQUENCE_EQUAL(first, second)

• If first and second do not have equal elements, the test will fail.
• first and second may be any sequence types (e.g. arrays, vectors, lists), as long as their elements are comparable with ==.

Command line options

$ ./my_tests.exe -h
usage: ./my_tests.exe [-h] [-n] [-q] [[TEST_NAME] ...]
optional arguments:
 -h, --help	             show this help message and exit
 -n, --show_test_names	 print the names of all discovered test cases and exit
 -q, --quiet             print a reduced summary of test results
 TEST_NAME ...           run only the test cases whose names are listed here. Note: If no test names are specified, all discovered tests are run by default.

$ ./my_tests.exe --show_test_names
bool_is_true
numbers_equal

$ ./my_tests.exe --quiet
*** Results ***
bool_is_true: PASS
numbers_equal: PASS

$ ./my_tests.exe bool_is_true
Running test: bool_is_true
PASS

*** Results ***
** Test case 'bool_is_true': PASS
*** Summary ***
Out of 1 tests run:
0 failure(s), 0 error(s)