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 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");
}
};
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for