UsingCppUTest.md

Using Approval Tests With CppUTest

Contents

• Introduction
  • CppUTest Integration Limitations
• Requirements
• Getting Started With CppUTest
  • Starter Project
  • New Project
  • Existing Project - with your main()
• Code to copy for your first CppUTest Approvals test

Introduction

The CppUTest test framework works well on most platforms with Approval Tests.

This section describes the various ways of using Approval Tests with CppUTest.

---

Notes pre-v.10.8.0:

Earlier versions of Approval Tests had issues with Ninja. Read more at Troubleshooting Misconfigured Build.

CppUTest Integration Limitations

Note: This integration is not tested on CygWin. The CppUTest integration with Approval Tests does not build on this platform, CygWin, therefore our tests of it are disabled.

Note: Approval Tests's use of STL objects triggers test failures from CppUTest's memory-leak checking, and so our integration with CppUTest currently turns of its memory leak checks.

Requirements

Approval Tests requires that the following are found:

#include <CppUTest/CommandLineTestRunner.h>
#include <CppUTest/TestPlugin.h>
#include <CppUTest/TestRegistry.h>

^{snippet source | anchor}

Approval Tests is tested with CppUTest v4.0.

Getting Started With CppUTest

Starter Project

We haven't yet provided a Starter Project for using Approval Tests with CppUTest.

This is partly based on the assumption that anyone already using CppUTest will have their own project set up, and anyone else would probably use Catch2 instead.

If it would be helpful for us to such a Starter Project, please let us know, via the contact details in Contributing to ApprovalTests.cpp.

New Project

Create a file main.cpp and add just the following two lines:

#define APPROVALS_CPPUTEST
#include "ApprovalTests.hpp"

^{snippet source | anchor}

Existing Project - with your main()

If you have an existing CppUTest-based test program that provides its own main(), you won't be able to use the approach above.

Instead, you should make the following additions to your own source file that contains main().

// main.cpp:

// 1. Add these two lines to your main:
#define APPROVALS_CPPUTEST_EXISTING_MAIN
#include "ApprovalTests.hpp"

int main(int argc, char** argv)
{
    // 2. Add this line to your main:
    ApprovalTests::initializeApprovalTestsForCppUTest();

    int result = CommandLineTestRunner::RunAllTests(argc, argv);
    TestRegistry::getCurrentRegistry()->resetPlugins();
    return result;
}

^{snippet source | anchor}

Code to copy for your first CppUTest Approvals test

Here is sample code to create your main() function, to set up Approval Tests' CppUTest integration.

We called this file cpputest_starter_main.cpp:

#define APPROVALS_CPPUTEST
#include "ApprovalTests.hpp"

// This puts "received" and "approved" files in approval_tests/ sub-directory,
// keeping the test source directory tidy:
auto directoryDisposer =
    ApprovalTests::Approvals::useApprovalsSubdirectory("approval_tests");

^{snippet source | anchor}

Here is sample code to create your first test. We called this file cpputest_starter_test.cpp:

#include "ApprovalTests.hpp"
#include "CppUTest/TestHarness.h"

TEST_GROUP(CppUTestStarter){};

TEST(CppUTestStarter, Sample)
{
    // TODO Replace 42 with the value or object whose contents you are verifying.
    // For help, see:
    // https://approvaltestscpp.readthedocs.io/en/latest/generated_docs/ToString.html
    ApprovalTests::Approvals::verify(42);
}

^{snippet source | anchor}

And finally, here is sample code to put in your CMakeLists.txt file:

set(EXE_NAME cpputest_starter)
set(CMAKE_CXX_STANDARD 11)
add_executable(${EXE_NAME}
        cpputest_starter_main.cpp
        cpputest_starter_test.cpp
        )
target_link_libraries(${EXE_NAME} ApprovalTests::ApprovalTests CppUTest)

add_test(NAME ${EXE_NAME} COMMAND ${EXE_NAME})

^{snippet source | anchor}

---

Back to User Guide