Microsoft.VisualStudio.TestTools.CppUnitTestFramework API reference
Applies to: 
Visual Studio 
Visual 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
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");
}
};