Partager via

Microsoft.VisualStudio.TestTools.CppUnitTestFramework API reference

  • Article

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

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 and lib files are located under <Visual Studio installation folder>\VC\Auxiliary\VS\UnitTest.

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 namespace 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 scope of 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