Unit Test Framework
A lightweight, easy to use, C++11 unit testing framework implemented in a single .hpp
file.
Publicly available tutorial: https://eecs280staff.github.io/unit_test_framework/
Quickstart
Install the unit test framework by copying unit_test_framework.hpp
into your project.
$ wget https://raw.githubusercontent.com/eecs280staff/unit_test_framework/main/unit_test_framework.hpp
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.hpp"
// 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()
TEST()
macro
How to write a test case: The Test cases can be declared using the special TEST()
macro defined in unit_test_framework.hpp
:
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
andsecond
may be any type
ASSERT_NOT_EQUAL(first, second)
- If
first != second
evaluates to false, the test will fail. first
andsecond
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
andsecond
are not equal withinprecision
, the test will fail.
ASSERT_SEQUENCE_EQUAL(first, second)
- If
first
andsecond
do not have equal elements, the test will fail. first
andsecond
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)
Enabling regular expressions
By default, the unit test framework looks for exact matches to the
test names supplied at the command line. Matching via regular
expressions can be enabled by defining the UNIT_TEST_ENABLE_REGEXP
macro to 1 prior to #including unit_test_framework.hpp
(or when
compiling the test executable, such as with
-DUNIT_TEST_ENABLE_REGEXP
for GCC or Clang), and then passing the
-e
flag to the test executable.
$ g++ -std=c++11 -DUNIT_TEST_ENABLE_REGEXP -o my_tests.exe my_tests.cpp
$ ./my_tests.exe -h
usage: ./my_tests.exe [-h] [-e] [-n] [-q] [[TEST_NAME] ...]
optional arguments:
-h, --help show this help message and exit
-e, --regexp treat TEST_NAME as a regular expression
-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 -e "bool.*"
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)