Microsoft.VisualStudio.TestTools.CppUnitTestFramework API reference

This topic lists the public members of the Microsoft::VisualStudio::CppUnitTestFramework namespace. Use these APIs to write C++ unit tests based on the Microsoft Native Unit Test Framework. There is a Usage Example at the end of the topic.

The header files are located in the VisualStudio2012[x86]InstallFolder\VC\UnitTest\include folder.

The lib files are located in the VisualStudio2012[x86]InstallFolder\VC\UnitTest\lib folder.

Header and lib paths are automatically configured in a Native Test project.

In this topic

CppUnitTest.h

CppUnitTest.h

Create test classes and methods

TEST_CLASS(className)

Required for each class containing test methods. Identifies className as a test class. TEST_CLASS must be declared at namescape scope.

TEST_METHOD(methodName)
{
    // test method body
}

Defines methodName as a test method. TEST_METHOD must be declared in the scope of the method's class.

Initialize and cleanup

Test methods

TEST_METHOD_INITIALIZE(methodName)
{
    // method initialization code
}

Defines methodName as a method that runs before each test method is run. TEST_METHOD_INITIALIZE can only be defined once in a test class and must be defined in the test class.

TEST_METHOD_CLEANUP(methodName)
{
    // test method cleanup  code
}

Defines methodName as a method that runs after each test method is run. TEST_METHOD_CLEANUP can only be defined once in a test class and must be defined in the scope of the test class.

Test classes

TEST_CLASS_INITIALIZE(methodName)
{
    // test class initialization  code
}

Defines methodName as a method that runs before each test class is created. TEST_CLASS_INITIALIZE can only be defined once in a test class and must be defined in the scope of the test class.

TEST_CLASS_CLEANUP(methodName)
{
    // test class cleanup  code
}

Defines methodName as a method that runs after each test class is created. TEST_CLASS_CLEANUP can only be defined once in a test class and must be defined in the scope of the test class.

Test modules

TEST_MODULE_INITIALIZE(methodName)
{
    // module initialization code
}

Defines the method methodName that runs when a module is loaded. TEST_MODULE_INITIALIZE can only be defined once in a test module and must be declared at namespace scope.

TEST_MODULE_CLEANUP(methodName)

Defines the method methodName that runs when a module is unloaded. TEST_MODULE_CLEANUP can only be defined once in a test module and must be declared at namespace scope.

Create test attributes

Test method attributes

BEGIN_TEST_METHOD_ATTRIBUTE(testMethodName)
    TEST_METHOD_ATTRIBUTE(attributeName, attributeValue)
    ...
END_TEST_METHOD_ATTRIBUTE()

Adds the attributes defined with one or more TEST_METHOD_ATTRIBUTE macros to the test method testMethodName.

A TEST_METHOD_ATTRIBUTE macro defines an attribute with the name attributeName and the value attributeValue.

Test class attributes

BEGIN_TEST_CLASS_ATTRIBUTE(testClassName)
    TEST_CLASS_ATTRIBUTE(attributeName, attributeValue)
    ...
END_TEST_CLASS_ATTRIBUTE()

Adds the attributes defined with one or more TEST_CLASS_ATTRIBUTE macros to the test class testClassName.

A TEST_CLASS_ATTRIBUTE macro defines an attribute with the name attributeName and the value attributeValue.

Test module attributes

BEGIN_TEST_MODULE_ATTRIBUTE(testModuleName)
    TEST_MODULE_ATTRIBUTE(attributeName, attributeValue)
    ...
END_TEST_MODULE_ATTRIBUTE()

Adds the attributes defined with one or more TEST_MODULE_ATTRIBUTE macros to the test module testModuleName.

A TEST_MODULE_ATTRIBUTE macro defines an attribute with the name attributeName and the value attributeValue.

Pre-defined attributes

These pre-defined attribute macros are provided as a convenience for common cases. They can be substituted for the macro TEST_METHOD_ATTRIBUTE described above.

TEST_OWNER(ownerAlias)

Defines a TEST_METHOD_ATTRIBUTE with the name Owner and the attribute value of ownerAlias.

TEST_DESCRIPTION(description)

Defines a TEST_METHOD_ATTRIBUTE with the name Description and the attribute value of description.

TEST_PRIORITY(priority)

Defines a TEST_METHOD_ATTRIBUTE with the name Priority and the attribute value of priority.

TEST_WORKITEM(workitem)

Defines a TEST_METHOD_ATTRIBUTE with the name WorkItem and the attribute value of workItem.

TEST_IGNORE()

Defines a TEST_METHOD_ATTRIBUTE with the name Ignore and the attribute value of true.

CppUnitTestAssert.h

General Asserts

Are Equal

Verify that two objects are equal

template<typename T>
static void Assert::AreEqual(
    const T& expected,
    const T& actual,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Verify that two doubles are equal

static void Assert::AreEqual(
    double expected,
    double actual,
    double tolerance,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Verify that two floats are equal

static void Assert::AreEqual(
    float expected,
    float actual,
    float tolerance,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Verify that two char* strings are equal

static void Assert::AreEqual(
    const char* expected,
    const char* actual,
    bool ignoreCase = false,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Verify that two w_char* strings are equal

static void Assert::AreEqual(
    const wchar_t* expected,
    const wchar_t* actual,
    bool ignoreCase = false,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Are Not Equal

Verify that two doubles are not equal

static void Assert::AreNotEqual(
    double notExpected,
    double actual,
    double tolerance,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Verify that two floats are not equal

static void Assert::AreNotEqual(
    float notExpected,
    float actual,
    float tolerance,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Verify that two char* strings are not equal

static void Assert::AreNotEqual(
    const char* notExpected,
    const char* actual,
    bool ignoreCase = false,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Verify that two w_char* strings are not equal

static void Assert::AreNotEqual(
    const wchar_t* notExpected,
    const wchar_t* actual,
    bool ignoreCase = false,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Verify that two references are not equal based on operator==.

template<typename T>
static void Assert::AreNotEqual(
    const T& notExpected,
    const T& actual,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Are Same

Verify that two references refer to the same object instance (identity).

template<typename T>
static void Assert::AreSame(
    const T& expected,
    const T& actual,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Are Not Same

Verify that two references do not refer to the same object instance (identity).

template<typename T>
static void Assert::AreNotSame (
    const T& notExpected,
    const T& actual,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Is Null

Verify that a pointer is NULL.

template<typename T>
static void Assert::IsNull(
    const T* actual,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Is Not Null

Verify that a pointer is not NULL

template<typename T>
static void Assert::IsNotNull(
    const T* actual,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Is True

Verify that a condition is true

static void Assert::IsTrue(
    bool condition,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Is False

Verify that a condition is false

static void Assert::IsFalse(
    bool condition,
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Fail

Force the test case result to be failed

static void Assert::Fail(
    const wchar_t* message = NULL,
    const __LineInfo* pLineInfo = NULL)

Windows Runtime Asserts

Are Equal

Verifies that two Windows Runtime pointers are equal.

template<typename T>
static void Assert::AreEqual(
    T^ expected,
    T^ actual,
    Platform::String^ message = nullptr,
    const __LineInfo* pLineInfo= nullptr)

Verifies that two Platform::String^ strings are equal.

template<typename T>
static void Assert::AreEqual(
    T^ expected,
    T^ actual,
    Platform::String^ message= nullptr,
    const __LineInfo* pLineInfo= nullptr)

Are Same

Verifies that two Windows Runtime references reference the same object.

template<typename T>
static void Assert::AreSame(
    T% expected,
    T% actual,
    Platform::String^ message= nullptr,
    const __LineInfo* pLineInfo= nullptr)

Are Not Equal

Verifies that two Windows Runtime pointers are not equal.

template<typename T>
static void Assert::AreNotEqual(
    T^ notExpected,
    T^ actual,
    Platform::String^ message = nullptr,
    const __LineInfo* pLineInfo= nullptr)

Verifies that two Platform::String^ strings are not equal.

static void Assert::AreNotEqual(
    Platform::String^ notExpected,
    Platform::String^ actual,
    bool ignoreCase = false,
    Platform::String^ message= nullptr,
    const __LineInfo* pLineInfo= nullptr)

Are Not Same

Verifies that two Windows Runtime references do not reference the same object.

template<typename T>
static void Assert::AreNotSame(
    T% notExpected,
    T% actual,
    Platform::String^ message= nullptr,
    const __LineInfo* pLineInfo= nullptr)

Is Null

Verifies that a Windows Runtime pointer is a nullptr.

template<typename T>
static void Assert::IsNull(
    T^ actual,
    Platform::String^ message = nullptr,
    const __LineInfo* pLineInfo= nullptr)

Is Not Null

Verifies that a Windows Runtime pointer is not a nullptr.

template<typename T>
static void Assert::IsNotNull(
    T^ actual,
    Platform::String^ message= nullptr,
    const __LineInfo* pLineInfo= nullptr)

Exception Asserts

Expect Exception

Verify that a function raises an exception:

template<typename _EXPECTEDEXCEPTION, typename _FUNCTOR>
static void Assert::ExpectException(
    _FUNCTOR functor,
    const wchar_t* message= NULL,
    const __LineInfo* pLineInfo= NULL)

Verify that a function raises an exception:

template<typename _EXPECTEDEXCEPTION, typename _RETURNTYPE>
    static void Assert::ExpectException(
    _RETURNTYPE (*func)(),
    const wchar_t* message= NULL,
    const __LineInfo* pLineInfo = NULL)

CppUnitTestLogger.h

Logger

The Logger class contains static methods to write to the Output Window.

Write Message

Write a string to the Output Window

static void Logger::WriteMessage(const wchar_t* message)
static void Logger::WriteMessage(const char* message)

Example

This code is an example of VSCppUnit usage. It includes examples of attribute metadata, fixtures, unit tests with assertions, and custom logging.

// USAGE EXAMPLE

#include <CppUnitTest.h>

using namespace Microsoft::VisualStudio::CppUnitTestFramework;

BEGIN_TEST_MODULE_ATTRIBUTE()
    TEST_MODULE_ATTRIBUTE(L"Date", L"2010/6/12")
END_TEST_MODULE_ATTRIBUTE()

TEST_MODULE_INITIALIZE(ModuleInitialize)
{
    Logger::WriteMessage("In Module Initialize");
}

TEST_MODULE_CLEANUP(ModuleCleanup)
{
    Logger::WriteMessage("In Module Cleanup");
}

TEST_CLASS(Class1)
{

public:

    Class1()
    {
        Logger::WriteMessage("In Class1");
    }

    ~Class1()
    {
        Logger::WriteMessage("In ~Class1");
    }

    TEST_CLASS_INITIALIZE(ClassInitialize)
    {
        Logger::WriteMessage("In Class Initialize");
    }

    TEST_CLASS_CLEANUP(ClassCleanup)
    {
        Logger::WriteMessage("In Class Cleanup");
    }

    BEGIN_TEST_METHOD_ATTRIBUTE(Method1)
        TEST_OWNER(L"OwnerName")
        TEST_PRIORITY(1)
    END_TEST_METHOD_ATTRIBUTE()

    TEST_METHOD(Method1)
    {
        Logger::WriteMessage("In Method1");
        Assert::AreEqual(0, 0);
    }

    TEST_METHOD(Method2)
    {
        Assert::Fail(L"Fail");
    }
};

See also