The Vespa test framework helps you write small applications to test C++ code. All interaction with the test framework is done with the use of macros.

The minimal test application looks like this:

The runnable application itself is called a test suite and inherits its name from the cpp file containing the TEST_MAIN macro. Each individual verification of some value is called a check. Checks can be put anywhere, but it is highly recommended that you put them inside tests. Tests are created by a family of macros. Another macro (TEST_RUN_ALL) is used to execute them.

Example with two tests, each containing a single check:

All checks are available in two variants. Those with the EXPECT_ prefix allow execution to continue even if a check fails. Those with the ASSERT_ prefix will terminate execution of the current test if it fails.

Checks involving comparison of values typically use == and < operators to compare values. Also; in order to be part of a comparison check, the value must support the << operator to print the value to a string stream in case the check fails.

Sometimes multiple tests wish to use the same predefined state as a starting point. This state is called a test fixture. Test fixtures are untangled from the actual tests and construction/destruction is used to handle their lifetime. When thinking of what can be used as a fixture, think of what can be put after new to create an object.

• A single test can have multiple test fixtures.
• The number of Fs in the test macro denotes the number of fixtures.
• Inside the test, fixtures are available as f1, f2 and so forth.
• Test fixtures can be parameterized with constructor parameters.
• Checks can be performed inside test fixture constructors.
• A test fixture constructor can take other test fixtures as input.

One of the most novel features of the test framework is the ability to write multi-threaded tests. Multi-threaded tests are created by using test macros containing _MT and supplying a thread count. All threads will execute the block of code encapsulated by the test. The test fixtures are shared among all threads. In addition, each thread has a variable named num_threads containing the total number of threads running the test and a variable named thread_id identifying the thread.

The TEST_BARRIER() macro can be used inside the test to synchronize the threads. The macro will block execution of each thread invoking it until all threads have invoked it.

Overall Execution Macros

• TEST_MAIN()
• TEST_RUN_ALL()

Test Creation Macros

• TEST(name)
• TEST_F(name, fixture)
• TEST_FF(name, fixture1, fixture2)
• TEST_FFF(name, fixture1, fixture2, fixture3)

• TEST_MT(name, threads)
• TEST_MT_F(name, threads, fixture)
• TEST_MT_FF(name, threads, fixture1, fixture2)
• TEST_MT_FFF(name, threads, fixture1, fixture2, fixture3)

• IGNORE_TEST(name)
• IGNORE_TEST_F(name, fixture)
• IGNORE_TEST_FF(name, fixture1, fixture2)
• IGNORE_TEST_FFF(name, fixture1, fixture2, fixture3)

• IGNORE_TEST_MT(name, threads)
• IGNORE_TEST_MT_F(name, threads, fixture)
• IGNORE_TEST_MT_FF(name, threads, fixture1, fixture2)
• IGNORE_TEST_MT_FFF(name, threads, fixture1, fixture2, fixture3)

Check Macros

• ASSERT_TRUE(rc)
• ASSERT_FALSE(rc)
• ASSERT_EQUAL(a, b)
• ASSERT_NOT_EQUAL(a, b)
• ASSERT_APPROX(a, b, eps)
• ASSERT_NOT_APPROX(a, b, eps)
• ASSERT_LESS(a, b)
• ASSERT_LESS_EQUAL(a, b)
• ASSERT_GREATER(a, b)
• ASSERT_GREATER_EQUAL(a, b)
• ASSERT_EXCEPTION(statement, exception_type, msg_substr)
• TEST_FATAL(msg)

• EXPECT_TRUE(rc)
• EXPECT_FALSE(rc)
• EXPECT_EQUAL(a, b)
• EXPECT_NOT_EQUAL(a, b)
• EXPECT_APPROX(a, b, eps)
• EXPECT_NOT_APPROX(a, b, eps)
• EXPECT_LESS(a, b)
• EXPECT_LESS_EQUAL(a, b)
• EXPECT_GREATER(a, b)
• EXPECT_GREATER_EQUAL(a, b)
• EXPECT_EXCEPTION(statement, exception_type, msg_substr)
• TEST_ERROR(msg)

Thread Macros

• TEST_BARRIER()

State Tracking Macros

• TEST_DO(doit)
• TEST_STATE(msg)

Macros of Limited Use

• TEST_TRACE()
• TEST_FLUSH()
• TEST_THREAD(name)
• TEST_DEBUG(lhsFile, rhsFile)
• TEST_MAIN_WITH_PROCESS_PROXY()