Google Test – 如何编写测试用例

1 概述

本页面列出了 GoogleTest 用于编写测试程序的功能。要使用它们，请添加 #include <gtest/gtest.h>。

2 宏

2.1 TEST

TEST(TestSuiteName, TestName) {
  ... statements ...
}

描述：定义了一个名为 TestName 的单独测试，属于测试套件 TestSuiteName，包含给定的语句。

参数要求：

• 参数 TestSuiteName 和 TestName 都必须是有效的 C++ 标识符，并且不能包含下划线（_）。
• 不同测试套件中的测试可以有相同的单独名称。

测试体：

• 测试体内的语句可以是任何被测试的代码。
• 测试体中使用的断言决定了测试的结果。

2.2 TEST_F

TEST_F(TestFixtureName, TestName) {
  ... statements ...
}

描述：定义了一个名为 TestName 的单独测试，使用测试夹具类 TestFixtureName。测试套件名称是 TestFixtureName。

参数要求：

• 参数 TestFixtureName 和 TestName 都必须是有效的 C++ 标识符，并且不能包含下划线（_）。
• TestFixtureName 必须是测试夹具类的名称——请参阅测试夹具。

测试体：

• 测试体内的语句可以是任何被测试的代码。
• 测试体中使用的断言决定了测试的结果。

2.3 TEST_P

TEST_P(TestFixtureName, TestName) {
  ... statements ...
}

描述：定义了一个名为 TestName 的单独值参数化测试，使用测试夹具类 TestFixtureName。测试套件名称是 TestFixtureName。

参数要求：

• 参数 TestFixtureName 和 TestName 都必须是有效的 C++ 标识符，并且不能包含下划线（_）。
• TestFixtureName 必须是值参数化测试夹具类的名称——请参阅值参数化测试。

测试体：

• 测试体内的语句可以是任何被测试的代码。
• 在测试体中，可以通过 GetParam() 函数访问测试参数（请参阅 WithParamInterface）。例如：

TEST_P(MyTestSuite, DoesSomething) {
  ...
  EXPECT_TRUE(DoSomething(GetParam()));
  ...
}

• 测试体中使用的断言决定了测试的结果。

相关函数：请参阅 INSTANTIATE_TEST_SUITE_P。

2.4 INSTANTIATE_TEST_SUITE_P

INSTANTIATE_TEST_SUITE_P(`InstantiationName`, `TestSuiteName`, `param_generator`)
INSTANTIATE_TEST_SUITE_P(`InstantiationName`, `TestSuiteName`, `param_generator`, `name_generator`)

描述：实例化值参数化测试套件 TestSuiteName（使用 TEST_P 定义）。

参数说明：

• 参数 InstantiationName 是测试套件实例化的唯一名称，用于区分多个实例化。在测试输出中，实例化名称被添加为测试套件名称 TestSuiteName 的前缀。如果 InstantiationName 为空（INSTANTIATE_TEST_SUITE_P(, ...)），则不添加前缀。
• 参数 param_generator 是以下 GoogleTest 提供的函数之一，用于生成测试参数，所有这些函数都定义在 ::testing 命名空间中：

参数生成器 行为 Range(begin, end [, step]) 生成值 {begin, begin+step, begin+step+step, ...}。值不包括 end。step 默认为 1。 Values(v1, v2, ..., vN) 生成值 {v1, v2, ..., vN}。 ValuesIn(container) 或 ValuesIn(begin,end) 从 C 风格数组、STL 风格容器或迭代器范围 [begin, end) 中生成值。 Bool() 生成序列 {false, true}。 Combine(g1, g2, ..., gN) 生成 std::tuple n-元组，包含由给定的 n 个生成器 g1, g2, …, gN 生成的所有值的组合（笛卡尔积）。 ConvertGenerator<T>(g) 或 ConvertGenerator(g, func) 生成由生成器 g 生成的值，并通过 static_cast 转换为 T。（注意：T 可能不是你期望的类型。请参阅下面的 Using ConvertGenerator）。第二个重载使用 func 来执行转换。

• 可选的最后一个参数 name_generator 是一个函数或函数对象，用于根据测试参数生成自定义测试名称后缀。该函数必须接受一个类型为 TestParamInfo<class ParamType> 的参数，并返回一个 std::string。测试名称后缀只能包含字母数字字符和下划线。GoogleTest 提供了 PrintToStringParamName，也可以使用自定义函数以获得更多的控制：

INSTANTIATE_TEST_SUITE_P(
    MyInstantiation, MyTestSuite,
    testing::Values(...),
    [](const testing::TestParamInfo<MyTestSuite::ParamType>& info) {
      // 可以在这里使用 info.param 来生成测试后缀
      std::string name = ...
      return name;
    });

相关函数：请参阅值参数化测试。

注意事项：请参阅 GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST。

2.4.1 使用 ConvertGenerator

描述：上表中列出的函数似乎返回生成所需类型值的生成器，但通常并非如此。相反，它们通常返回工厂对象，这些对象可以转换为所需的生成器。这为允许你指定与实际参数类型不同但可以隐式转换为实际参数类型的值提供了一些灵活性。

示例：

• 例如，你可以对需要 int 参数的夹具执行以下操作：

INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
    testing::Values(1, 1.2));  // 是的，Values() 支持异构参数类型。

• 1.2 是一个 double，似乎会隐式转换为 int，但实际上需要一些模板技巧，涉及前面段落中描述的间接性。

显式转换：

• 如果参数类型不能隐式转换为生成的类型，但可以显式转换，将不会自动进行转换，但你可以通过应用 ConvertGenerator<T> 强制进行转换。编译器可以自动推导目标类型（你的夹具的参数类型），但由于前面提到的间接性，它无法决定生成的类型应该是什么。你需要通过显式提供类型 T 来告诉它。因此，T 不应该是你的夹具的参数类型，而是一个中间类型，该类型由工厂对象支持，并且可以 static_cast 到夹具的参数类型：

// 夹具的参数类型。
class MyParam {
 public:
  // 显式转换构造函数。
  explicit MyParam(const std::tuple<int, bool>& t);
  ...
};

INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
    ConvertGenerator<std::tuple<int, bool>>(Combine(Values(0.1, 1.2), Bool())));

• 在这个例子中，Combine 支持生成 std::tuple<int, bool>> 对象（尽管为第一个元组元素提供的值是 double），这些 tuple 通过调用 ConvertGenerator 转换为 MyParam 对象。

自定义转换：

• 对于不能从生成的类型转换为参数类型的参数类型，你可以提供一个可调用对象来进行转换。该可调用对象接受一个生成类型的对象，并返回一个夹具的参数类型的对象。通常，生成的类型可以由编译器从可调用对象的调用签名中推导出来，因此你通常不需要显式指定它（但请参阅下面的注意事项）。

// 夹具的参数类型。
class MyParam {
 public:
  MyParam(int, bool);
  ...
};

INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
    ConvertGenerator(Combine(Values(1, 1.2), Bool()),
        [](const std::tuple<int, bool>& t){
          const auto [i, b] = t;
          return MyParam(i, b);
        }));

注意事项：

• 考虑以下示例。

INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,
    ConvertGenerator(Values(std::string("s")), [](std::string_view s) { ... }));

• string 参数被复制到 Values 返回的工厂对象中。然后，由于从 lambda 推导出的生成类型是 string_view，工厂对象生成一个持有引用该 string 的 string_view 的生成器。不幸的是，当这个生成器被调用时，工厂对象已经不存在了，string_view 是悬挂的。

• 要解决这个问题，你可以显式指定生成类型：

  ConvertGenerator<std::string>(Values(std::string("s")), [](std::string_view s) { ... })

或者，你可以将 lambda 的签名改为接受 std::string 或 const std::string&（后者不会导致悬挂引用，因为类型推导会去掉引用和 const）。

2.5 TYPED_TEST_SUITE

TYPED_TEST_SUITE(`TestFixtureName`, `Types`)
TYPED_TEST_SUITE(`TestFixtureName`, `Types`, `NameGenerator`)

描述：基于测试夹具 TestFixtureName 定义一个类型化测试套件。测试套件名称是 TestFixtureName。

参数要求：

• 参数 TestFixtureName 是一个模板化的测试夹具类，以类型为参数，例如：

template <typename T>
class MyFixture : public testing::Test {
 public:
  ...
  using List = std::list<T>;
  static T shared_;
  T value_;
};

• 参数 Types 是一个 Types 对象，表示要运行测试的类型列表，例如：

using MyTypes = ::testing::Types<char, int, unsigned int>;
TYPED_TEST_SUITE(MyFixture, MyTypes);

• 类型别名（using 或 typedef）对于 TYPED_TEST_SUITE 宏的正确解析是必需的。

• 可选的第三个参数 NameGenerator 允许指定一个类，该类公开一个模板化的静态函数 GetName(int)。例如：

class NameGenerator {
 public:
  template <typename T>
  static std::string GetName(int) {
    if constexpr (std::is_same_v<T, char>) return "char";
    if constexpr (std::is_same_v<T, int>) return "int";
    if constexpr (std::is_same_v<T, unsigned int>) return "unsignedInt";
  }
};
TYPED_TEST_SUITE(MyFixture, MyTypes, NameGenerator);

相关函数：请参阅 TYPED_TEST 和类型化测试。

2.6 TYPED_TEST

TYPED_TEST(TestSuiteName, TestName) {
  ... statements ...
}

描述：定义了一个名为 TestName 的单独类型化测试，属于类型化测试套件 TestSuiteName。测试套件必须使用 TYPED_TEST_SUITE 定义。

测试体：

• 在测试体中，特殊名称 TypeParam 表示类型参数，TestFixture 表示夹具类。请参阅以下示例：

TYPED_TEST(MyFixture, Example) {
  // 在测试中，使用特殊名称 TypeParam 获取类型参数。由于我们在派生类模板中，C++ 要求我们通过 'this' 访问 MyFixture 的成员。
  TypeParam n = this->value_;

  // 要访问夹具的静态成员，请添加 'TestFixture::' 前缀。
  n += TestFixture::shared_;

  // 要引用夹具中的类型定义，请添加 'typename TestFixture::' 前缀。'typename' 是必需的，以满足编译器的要求。
  typename TestFixture::List values;

  values.push_back(n);
  ...
}

相关函数：请参阅类型化测试。

2.7 TYPED_TEST_SUITE_P

TYPED_TEST_SUITE_P(`TestFixtureName`)

描述：基于测试夹具 TestFixtureName 定义一个类型参数化测试套件。测试套件名称是 TestFixtureName。

参数要求：

• 参数 TestFixtureName 是一个以类型为参数的模板化测试夹具类。请参阅 TYPED_TEST_SUITE 的示例。

相关函数：请参阅 TYPED_TEST_P 和类型参数化测试。

2.8 TYPED_TEST_P

TYPED_TEST_P(TestSuiteName, TestName) {
  ... statements ...
}

描述：定义了一个名为 TestName 的单独类型参数化测试，属于类型参数化测试套件 TestSuiteName。测试套件必须使用 TYPED_TEST_SUITE_P 定义。

测试体：

• 在测试体中，特殊名称 TypeParam 表示类型参数，TestFixture 表示夹具类。请参阅 TYPED_TEST 的示例。

相关函数：请参阅 REGISTER_TYPED_TEST_SUITE_P 和类型参数化测试。

2.9 REGISTER_TYPED_TEST_SUITE_P

REGISTER_TYPED_TEST_SUITE_P(`TestSuiteName`, `TestNames...`)

描述：注册测试套件 TestSuiteName 中的类型参数化测试 TestNames...。测试套件和测试必须使用 TYPED_TEST_SUITE_P 和 TYPED_TEST_P 定义。

示例：

// 定义测试套件和测试。
TYPED_TEST_SUITE_P(MyFixture);
TYPED_TEST_P(MyFixture, HasPropertyA) { ... }
TYPED_TEST_P(MyFixture, HasPropertyB) { ... }

// 在测试套件中注册测试。
REGISTER_TYPED_TEST_SUITE_P(MyFixture, HasPropertyA, HasPropertyB);

相关函数：请参阅 INSTANTIATE_TYPED_TEST_SUITE_P 和类型参数化测试。

2.10 INSTANTIATE_TYPED_TEST_SUITE_P

INSTANTIATE_TYPED_TEST_SUITE_P(`InstantiationName`, `TestSuiteName`, `Types`)

描述：实例化类型参数化测试套件 TestSuiteName。测试套件必须使用 REGISTER_TYPED_TEST_SUITE_P 注册。

参数要求：

• 参数 InstantiationName 是测试套件实例化的唯一名称，用于区分多个实例化。在测试输出中，实例化名称被添加为测试套件名称 TestSuiteName 的前缀。如果 InstantiationName 为空（INSTANTIATE_TYPED_TEST_SUITE_P(, ...)），则不添加前缀。
• 参数 Types 是一个 Types 对象，表示要运行测试的类型列表，例如：

using MyTypes = ::testing::Types<char, int, unsigned int>;
INSTANTIATE_TYPED_TEST_SUITE_P(MyInstantiation, MyFixture, MyTypes);

• 类型别名（using 或 typedef）对于 INSTANTIATE_TYPED_TEST_SUITE_P 宏的正确解析是必需的。

相关函数：请参阅类型参数化测试。

2.11 FRIEND_TEST

FRIEND_TEST(`TestSuiteName`, `TestName`)

描述：在类体中，将单独的测试声明为类的友元，允许测试访问类的私有成员。

注意事项：

• 如果类定义在命名空间中，则为了成为类的友元，测试夹具和测试必须在完全相同的命名空间中定义，不能使用内联或匿名命名空间。

示例：

• 如果类定义如下：

namespace my_namespace {

class MyClass {
  friend class MyClassTest;
  FRIEND_TEST(MyClassTest, HasPropertyA);
  FRIEND_TEST(MyClassTest, HasPropertyB);
  ... definition of class MyClass ...
};

}  // namespace my_namespace

• 那么测试代码应该如下：

namespace my_namespace {

class MyClassTest : public testing::Test {
  ...
};

TEST_F(MyClassTest, HasPropertyA) { ... }
TEST_F(MyClassTest, HasPropertyB) { ... }

}  // namespace my_namespace

相关函数：请参阅测试私有代码。

2.12 SCOPED_TRACE

SCOPED_TRACE(`message`)

描述：将当前文件名、行号以及给定的消息 message 添加到作用域内每个断言失败的失败消息中。

相关函数：请参阅为断言添加跟踪信息。

相关类：请参阅 ScopedTrace 类。

2.13 GTEST_SKIP

GTEST_SKIP()

描述：在运行时阻止进一步的测试执行。

使用场景：

• 可以在单独的测试用例中使用，也可以在测试环境或测试夹具（派生自 Environment 或 Test 类的类）的 SetUp() 方法中使用。如果在全局测试环境的 SetUp() 方法中使用，它将跳过测试程序中的所有测试。如果在测试夹具的 SetUp() 方法中使用，它将跳过相应测试套件中的所有测试。

自定义消息：

• 与断言类似，GTEST_SKIP 允许向其流式传输自定义消息。

相关函数：请参阅跳过测试执行。

2.14 GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST

GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST(`TestSuiteName`)

描述：允许值参数化测试套件 TestSuiteName 未实例化。

默认行为：

• 默认情况下，每个没有对应 INSTANTIATE_TEST_SUITE_P 调用的 TEST_P 调用都会在测试套件 GoogleTestVerification 中导致一个失败的测试。
• GTEST_ALLOW_UNINSTANTIATED_PARAMETERIZED_TEST 会抑制给定测试套件的此失败。

3. 类和类型

GoogleTest 定义了以下类和类型，以帮助编写测试。

3.1 AssertionResult

testing::AssertionResult

描述：一个用于指示断言是否成功的类。

失败消息：

• 当断言未成功时，AssertionResult 对象存储一个非空的失败消息，可以通过对象的 message() 方法检索该消息。

创建实例：

• 要创建此类的实例，请使用工厂函数 AssertionSuccess() 或 AssertionFailure()。

3.2 AssertionException

testing::AssertionException

描述：可以从 TestEventListener::OnTestPartResult 中抛出的异常。

3.3 EmptyTestEventListener

testing::EmptyTestEventListener

描述：为 TestEventListener 接口中的所有方法提供空实现，使得子类只需重写其关心的方法即可。

3.4 Environment

testing::Environment

描述：表示一个全局测试环境。请参阅全局设置和清理。

3.4.1 受保护的方法

3.4.1.1 SetUp

virtual void Environment::SetUp()

描述：重写此方法以定义如何设置环境。

3.4.1.2 TearDown

virtual void Environment::TearDown()

描述：重写此方法以定义如何清理环境。

3.5 ScopedTrace

testing::ScopedTrace

描述：此类的一个实例会导致在 ScopedTrace 实例的生命周期内，由代码生成的每个测试失败消息中都包含一个跟踪信息。当实例被销毁时，此效果将被撤销。

构造函数：

template <typename T>
ScopedTrace(const char* file, int line, const T& message)

示例用法：

testing::ScopedTrace trace("file.cc", 123, "message");

• 生成的跟踪信息包括给定的源文件路径和行号，以及给定的消息。message 参数可以是任何可以流式传输到 std::ostream 的东西。

相关函数：请参阅 SCOPED_TRACE。

3.6 Test

testing::Test

描述：所有测试继承的抽象类。Test 不可复制。

3.6.1 公共方法

3.6.1.1 SetUpTestSuite

static void Test::SetUpTestSuite()

描述：为测试套件中的所有测试执行共享的设置。GoogleTest 在运行测试套件中的第一个测试之前调用 SetUpTestSuite()。

3.6.1.2 TearDownTestSuite

static void Test::TearDownTestSuite()

描述：为测试套件中的所有测试执行共享的清理。GoogleTest 在运行测试套件中的最后一个测试之后调用 TearDownTestSuite()。

3.6.1.3 HasFatalFailure

static bool Test::HasFatalFailure()

描述：如果当前测试有致命失败，则返回 true。

3.6.1.4 HasNonfatalFailure

static bool Test::HasNonfatalFailure()

描述：如果当前测试有非致命失败，则返回 true。

3.6.1.5 HasFailure

static bool Test::HasFailure()

描述：如果当前测试有任何失败（致命或非致命），则返回 true。

3.6.1.6 IsSkipped

static bool Test::IsSkipped()

描述：如果当前测试被跳过，则返回 true。

3.6.1.7 RecordProperty

static void Test::RecordProperty(const std::string& key, const std::string& value)
static void Test::RecordProperty(const std::string& key, int value)

描述：记录当前测试、测试套件或整个测试程序运行的属性。只有最后一个给定键的值会被记录。

键的要求：

• 键必须是有效的 XML 属性名称，且不能与 GoogleTest 已经使用的名称冲突（name、file、line、status、time、classname、type_param 和 value_param）。

静态方法：

• RecordProperty 是 public static，因此可以从非测试夹具成员的工具函数中调用。

记录位置：

• 在测试的生命周期内（从构造函数开始到析构函数结束）调用 RecordProperty 的记录将在 XML 中作为 <testcase> 元素的属性输出。
• 在夹具的 SetUpTestSuite 或 TearDownTestSuite 方法中记录的属性将作为相应 <testsuite> 元素的属性输出。
• 在全局上下文（在调用 RUN_ALL_TESTS 之前或之后，或从注册的 Environment 对象的 SetUp/TearDown 方法中）调用 RecordProperty 的记录将作为 <testsuites> 元素的属性输出。

3.6.2 受保护的方法

3.6.2.1 SetUp

virtual void Test::SetUp()

描述：重写此方法以执行测试夹具的设置。GoogleTest 在运行每个单独的测试之前调用 SetUp()。

3.6.2.2 TearDown

virtual void Test::TearDown()

描述：重写此方法以执行测试夹具的清理。GoogleTest 在运行每个单独的测试之后调用 TearDown()。

3.7 TestWithParam

testing::TestWithParam<T>

描述：一个便利类，继承自 Test 和 WithParamInterface<T>。

3.8 TestSuite

描述：表示一个测试套件。TestSuite 不可复制。

3.8.1 公共方法

3.8.1.1 name

const char* TestSuite::name() const

描述：获取测试套件的名称。

3.8.1.2 type_param

const char* TestSuite::type_param() const

描述：返回参数类型的名称，如果不是类型化或类型参数化测试套件，则返回 NULL。请参阅类型化测试和类型参数化测试。

3.8.1.3 should_run

bool TestSuite::should_run() const

描述：如果此测试套件中的任何测试应该运行，则返回 true。

3.8.1.4 successful_test_count

int TestSuite::successful_test_count() const

描述：获取此测试套件中成功的测试数量。

3.8.1.5 skipped_test_count

int TestSuite::skipped_test_count() const

描述：获取此测试套件中被跳过的测试数量。

3.8.1.6 failed_test_count

int TestSuite::failed_test_count() const

描述：获取此测试套件中失败的测试数量。

3.8.1.7 reportable_disabled_test_count

int TestSuite::reportable_disabled_test_count() const

描述：获取将在 XML 报告中报告的已禁用测试的数量。

3.8.1.8 disabled_test_count

int TestSuite::disabled_test_count() const

描述：获取此测试套件中已禁用的测试数量。

3.8.1.9 reportable_test_count

int TestSuite::reportable_test_count() const

描述：获取将在 XML 报告中打印的测试数量。

3.8.1.10 test_to_run_count

int TestSuite::test_to_run_count() const

描述：获取此测试套件中应该运行的测试数量。

3.8.1.11 total_test_count

int TestSuite::total_test_count() const

描述：获取此测试套件中的所有测试数量。

3.8.1.12 Passed

bool TestSuite::Passed() const

描述：如果测试套件通过，则返回 true。

3.8.1.13 Failed

bool TestSuite::Failed() const

描述：如果测试套件失败，则返回 true。

3.8.1.14 elapsed_time

TimeInMillis TestSuite::elapsed_time() const

描述：返回经过的时间，以毫秒为单位。

3.8.1.15 start_timestamp

TimeInMillis TestSuite::start_timestamp() const

描述：获取测试套件开始的时间，从 UNIX 纪元开始的毫秒数。

3.8.1.16 GetTestInfo

const TestInfo* TestSuite::GetTestInfo(int i) const

描述：返回所有测试中的第 i 个测试的 TestInfo。i 的范围可以从 0 到 total_test_count() - 1。如果 i 不在此范围内，则返回 NULL。

3.8.1.17 ad_hoc_test_result

const TestResult& TestSuite::ad_hoc_test_result() const

描述：返回包含在 SetUpTestSuite 和 TearDownTestSuite 执行期间记录的测试属性的 TestResult。

3.9 TestInfo

testing::TestInfo

描述：存储有关测试的信息。

3.9.1 公共方法

3.9.1.1 test_suite_name

const char* TestInfo::test_suite_name() const

描述：返回测试套件名称。

3.9.1.2 name

const char* TestInfo::name() const

描述：返回测试名称。

3.9.1.3 type_param

const char* TestInfo::type_param() const

描述：返回参数类型的名称，如果不是类型化或类型参数化测试，则返回 NULL。请参阅类型化测试和类型参数化测试。

3.9.1.4 value_param

const char* TestInfo::value_param() const

描述：返回值参数的文本表示，如果不是值参数化测试，则返回 NULL。请参阅值参数化测试。

3.9.1.5 file

const char* TestInfo::file() const

描述：返回定义此测试的文件名。

3.9.1.6 line

int TestInfo::line() const

描述：返回定义此测试的行号。

3.9.1.7 is_in_another_shard

bool TestInfo::is_in_another_shard() const

描述：如果此测试不应运行因为它属于另一个分片，则返回 true。

3.9.1.8 should_run

bool TestInfo::should_run() const

描述：如果测试应该运行，则返回 true，即测试未被禁用（或者它被禁用了，但指定了 also_run_disabled_tests 标志），并且其全名与用户指定的过滤器匹配。

测试过滤：

• GoogleTest 允许用户按测试的全名过滤测试。只有匹配过滤器的测试才会运行。请参阅运行测试子集以获取更多信息。

3.9.1.9 is_reportable

bool TestInfo::is_reportable() const

描述：如果此测试将出现在 XML 报告中，则返回 true。

3.9.1.10 result

const TestResult* TestInfo::result() const

描述：返回测试的结果。请参阅 TestResult。

3.10 TestParamInfo

testing::TestParamInfo<T>

描述：描述值参数化测试的一个参数。类型 T 是参数的类型。

成员变量：

• 包含字段 param 和 index，分别保存参数的值及其整数索引。

3.11 UnitTest

testing::UnitTest

描述：此类包含有关测试程序的信息。

UnitTest 是一个单例类。第一次调用 UnitTest::GetInstance() 时会创建一个 UnitTest 对象。此实例永远不会被删除。

UnitTest 不可复制。

3.11.1 公共方法

3.11.1.1 GetInstance

static UnitTest* UnitTest::GetInstance()

描述：获取单例 UnitTest 对象。首次调用此方法时，会构造一个 UnitTest 对象并返回。后续调用将返回同一个对象。

3.11.1.2 original_working_dir

const char* UnitTest::original_working_dir() const

描述：返回第一个 TEST() 或 TEST_F() 执行时的工作目录。UnitTest 对象拥有该字符串。

3.11.1.3 current_test_suite

const TestSuite* UnitTest::current_test_suite() const

描述：返回当前正在运行的测试的 TestSuite 对象，如果没有测试正在运行，则返回 NULL。

3.11.1.4 current_test_info

const TestInfo* UnitTest::current_test_info() const

描述：返回当前正在运行的测试的 TestInfo 对象，如果没有测试正在运行，则返回 NULL。

3.11.1.5 random_seed

int UnitTest::random_seed() const

描述：返回当前测试运行开始时使用的随机种子。

3.11.1.6 successful_test_suite_count

int UnitTest::successful_test_suite_count() const

描述：获取成功的测试套件数量。

3.11.1.7 failed_test_suite_count

int UnitTest::failed_test_suite_count() const

描述：获取失败的测试套件数量。

3.11.1.8 total_test_suite_count

int UnitTest::total_test_suite_count() const

描述：获取所有测试套件的数量。

3.11.1.9 test_suite_to_run_count

int UnitTest::test_suite_to_run_count() const

描述：获取至少包含一个应该运行的测试的所有测试套件的数量。

3.11.1.10 successful_test_count

int UnitTest::successful_test_count() const

描述：获取成功的测试数量。

3.11.1.11 skipped_test_count

int UnitTest::skipped_test_count() const

描述：获取被跳过的测试数量。

3.11.1.12 failed_test_count

int UnitTest::failed_test_count() const

描述：获取失败的测试数量。

3.11.1.13 reportable_disabled_test_count

int UnitTest::reportable_disabled_test_count() const

描述：获取将在 XML 报告中报告的已禁用测试的数量。

3.11.1.14 disabled_test_count

int UnitTest::disabled_test_count() const

描述：获取已禁用的测试数量。

3.11.1.15 reportable_test_count

int UnitTest::reportable_test_count() const

描述：获取将在 XML 报告中打印的测试数量。

3.11.1.16 total_test_count

int UnitTest::total_test_count() const

描述：获取所有测试的数量。

3.11.1.17 test_to_run_count

int UnitTest::test_to_run_count() const

描述：获取应该运行的测试数量。

3.11.1.18 start_timestamp

TimeInMillis UnitTest::start_timestamp() const

描述：获取测试程序开始的时间，从 UNIX 纪元开始的毫秒数。

3.11.1.19 elapsed_time

TimeInMillis UnitTest::elapsed_time() const

描述：获取经过的时间，以毫秒为单位。

3.11.1.20 Passed

bool UnitTest::Passed() const

描述：如果单元测试通过（即所有测试套件都通过），则返回 true。

3.11.1.21 Failed

bool UnitTest::Failed() const

描述：如果单元测试失败（即某个测试套件失败，或者在所有测试之外发生失败），则返回 true。

3.11.1.22 GetTestSuite

const TestSuite* UnitTest::GetTestSuite(int i) const

描述：返回所有测试套件中的第 i 个测试套件的 TestSuite 对象。i 的范围可以从 0 到 total_test_suite_count() - 1。如果 i 不在此范围内，则返回 NULL。

3.11.1.23 ad_hoc_test_result

const TestResult& UnitTest::ad_hoc_test_result() const

描述：返回包含在各个测试套件之外记录的测试失败和属性信息的 TestResult。

3.11.1.24 listeners

TestEventListeners& UnitTest::listeners()

描述：返回可用于跟踪 GoogleTest 内部事件的事件监听器列表。请参阅 TestEventListeners。

3.12 TestEventListener

testing::TestEventListener

描述：用于跟踪测试执行的接口。下面列出的方法是按照相应事件触发的顺序排列的。

3.12.1 公共方法

3.12.1.1 OnTestProgramStart

virtual void TestEventListener::OnTestProgramStart(const UnitTest& unit_test)

描述：在任何测试活动开始之前触发。

3.12.1.2 OnTestIterationStart

virtual void TestEventListener::OnTestIterationStart(const UnitTest& unit_test, int iteration)

描述：在每次测试迭代开始之前触发。如果设置了 GTEST_FLAG(repeat)，可能会有多个迭代。iteration 是迭代索引，从 0 开始。

3.12.1.3 OnEnvironmentsSetUpStart

virtual void TestEventListener::OnEnvironmentsSetUpStart(const UnitTest& unit_test)

描述：在每次测试迭代的环境设置开始之前触发。

3.12.1.4 OnEnvironmentsSetUpEnd

virtual void TestEventListener::OnEnvironmentsSetUpEnd(const UnitTest& unit_test)

描述：在每次测试迭代的环境设置结束之后触发。

3.12.1.5 OnTestSuiteStart

virtual void TestEventListener::OnTestSuiteStart(const TestSuite& test_suite)

描述：在测试套件开始之前触发。

3.12.1.6 OnTestStart

virtual void TestEventListener::OnTestStart(const TestInfo& test_info)

描述：在测试开始之前触发。

3.12.1.7 OnTestPartResult

virtual void TestEventListener::OnTestPartResult(const TestPartResult& test_part_result)

描述：在失败的断言或 SUCCEED() 调用之后触发。如果你想从这个函数中抛出异常以跳到下一个测试，它必须是 AssertionException 或其派生类。

3.12.1.8 OnTestEnd

virtual void TestEventListener::OnTestEnd(const TestInfo& test_info)

描述：在测试结束之后触发。

3.12.1.9 OnTestSuiteEnd

virtual void TestEventListener::OnTestSuiteEnd(const TestSuite& test_suite)

描述：在测试套件结束之后触发。

3.12.1.10 OnEnvironmentsTearDownStart

virtual void TestEventListener::OnEnvironmentsTearDownStart(const UnitTest& unit_test)

描述：在每次测试迭代的环境清理开始之前触发。

3.12.1.11 OnEnvironmentsTearDownEnd

virtual void TestEventListener::OnEnvironmentsTearDownEnd(const UnitTest& unit_test)

描述：在每次测试迭代的环境清理结束之后触发。

3.12.1.12 OnTestIterationEnd

virtual void TestEventListener::OnTestIterationEnd(const UnitTest& unit_test, int iteration)

描述：在每次测试迭代结束之后触发。

3.12.1.13 OnTestProgramEnd

virtual void TestEventListener::OnTestProgramEnd(const UnitTest& unit_test)

描述：在所有测试活动结束之后触发。

3.13 TestEventListeners

testing::TestEventListeners

描述：允许用户添加监听器以跟踪 GoogleTest 内部的事件。

3.13.1 公共方法

3.13.1.1 Append

void TestEventListeners::Append(TestEventListener* listener)

描述：将事件监听器追加到列表的末尾。GoogleTest 假设它拥有该监听器（即它将在测试程序结束时删除该监听器）。

3.13.1.2 Release

TestEventListener* TestEventListeners::Release(TestEventListener* listener)

描述：从列表中移除给定的事件监听器并返回它。然后由调用者负责删除该监听器。如果监听器未在列表中找到，则返回 NULL。

3.13.1.3 default_result_printer

TestEventListener* TestEventListeners::default_result_printer() const

描述：返回负责默认控制台输出的标准监听器。可以通过从监听器列表中移除它来关闭默认的控制台输出。注意，使用 Release() 从监听器列表中移除该对象会将其所有权转移给调用者，并且下次调用此函数时将返回 NULL。

3.13.1.4 default_xml_generator

TestEventListener* TestEventListeners::default_xml_generator() const

描述：返回由 --gtest_output=xml 标志控制的默认 XML 输出的标准监听器。用户可以通过从监听器列表中移除它来关闭该标志控制的默认 XML 输出，并替换为自定义的输出。注意，使用 Release() 从监听器列表中移除该对象会将其所有权转移给调用者，并且下次调用此函数时将返回 NULL。

3.14 TestPartResult

testing::TestPartResult

描述：一个可复制的对象，表示测试部分（即断言或显式的 FAIL()、ADD_FAILURE() 或 SUCCESS()）的结果。

3.14.1 公共方法

3.14.1.1 type

Type TestPartResult::type() const

描述：获取测试部分的结果。

返回类型 Type 是一个枚举，定义如下：

enum Type {
  kSuccess,          // 成功。
  kNonFatalFailure,  // 失败但测试可以继续。
  kFatalFailure,     // 失败且测试应终止。
  kSkip              // 跳过。
};

3.14.1.2 file_name

const char* TestPartResult::file_name() const

描述：获取发生测试部分的源文件名称，如果未知则返回 NULL。

3.14.1.3 line_number

int TestPartResult::line_number() const

描述：获取发生测试部分的源文件行号，如果未知则返回 -1。

3.14.1.4 summary

const char* TestPartResult::summary() const

描述：获取失败消息的摘要。

3.14.1.5 message

const char* TestPartResult::message() const

描述：获取与测试部分相关联的消息。

3.14.1.6 skipped

bool TestPartResult::skipped() const

描述：如果测试部分被跳过，则返回 true。

3.14.1.7 passed

bool TestPartResult::passed() const

描述：如果测试部分通过，则返回 true。

3.14.1.8 nonfatally_failed

bool TestPartResult::nonfatally_failed() const

描述：如果测试部分非致命失败，则返回 true。

3.14.1.9 fatally_failed

bool TestPartResult::fatally_failed() const

描述：如果测试部分致命失败，则返回 true。

3.14.1.10 failed

bool TestPartResult::failed() const

描述：如果测试部分失败，则返回 true。

3.15 TestProperty

testing::TestProperty

描述：一个可复制的对象，表示用户指定的测试属性，可以作为键值字符串对输出。

3.15.1 公共方法

3.15.1.1 key

const char* key() const

描述：获取用户提供的键。

3.15.1.2 value

const char* value() const

描述：获取用户提供的值。

3.15.1.3 SetValue

void SetValue(const std::string& new_value)

描述：设置一个新值，覆盖之前的值。

3.16 TestResult

testing::TestResult

描述：包含有关单个测试结果的信息。

TestResult 不可复制。

3.16.1 公共方法

3.16.1.1 total_part_count

int TestResult::total_part_count() const

描述：获取所有测试部分的数量。这是成功测试部分数量和失败测试部分数量的总和。

3.16.1.2 test_property_count

int TestResult::test_property_count() const

描述：返回测试属性的数量。

3.16.1.3 Passed

bool TestResult::Passed() const

描述：如果测试通过（即没有任何测试部分失败），则返回 true。

3.16.1.4 Skipped

bool TestResult::Skipped() const

描述：如果测试被跳过，则返回 true。

3.16.1.5 Failed

bool TestResult::Failed() const

描述：如果测试失败，则返回 true。

3.16.1.6 HasFatalFailure

bool TestResult::HasFatalFailure() const

描述：如果测试致命失败，则返回 true。

3.16.1.7 HasNonfatalFailure

bool TestResult::HasNonfatalFailure() const

描述：如果测试有非致命失败，则返回 true。

3.16.1.8 elapsed_time

TimeInMillis TestResult::elapsed_time() const

描述：返回经过的时间，以毫秒为单位。

3.16.1.9 start_timestamp

TimeInMillis TestResult::start_timestamp() const

描述：获取测试用例开始的时间，从 UNIX 纪元开始的毫秒数。

3.16.1.10 GetTestPartResult

const TestPartResult& TestResult::GetTestPartResult(int i) const

描述：返回所有结果中的第 i 个测试部分结果。i 的范围可以从 0 到 total_part_count() - 1。如果 i 不在此范围内，则终止程序。

3.16.1.11 GetTestProperty

const TestProperty& TestResult::GetTestProperty(int i) const

描述：返回第 i 个测试属性的 TestProperty 对象。i 的范围可以从 0 到 test_property_count() - 1。如果 i 不在此范围内，则终止程序。

3.17 TimeInMillis

testing::TimeInMillis

描述：一个表示以毫秒为单位的时间的整数类型。

3.18 Types

testing::Types<T...>

描述：表示用于类型化测试和类型参数化测试的类型列表。

模板参数 T... 可以是任意数量的类型，例如：

testing::Types<char, int, unsigned int>

请参阅类型化测试和类型参数化测试以获取更多信息。

3.19 WithParamInterface

testing::WithParamInterface<T>

描述：所有值参数化测试继承的纯接口类。

值参数化测试夹具类必须继承自 Test 和 WithParamInterface。在大多数情况下，这意味着继承自 TestWithParam，但更复杂的测试层次结构可能需要在不同层次上继承自 Test 和 WithParamInterface。

此接口定义了类型别名 ParamType，用于参数类型 T，并支持通过 GetParam() 方法访问测试参数值：

static const ParamType& GetParam()

请参阅值参数化测试以获取更多信息。

4. 函数

GoogleTest 定义了以下函数，以帮助编写和运行测试。

4.1 InitGoogleTest

void testing::InitGoogleTest(int* argc, char** argv)
void testing::InitGoogleTest(int* argc, wchar_t** argv)
void testing::InitGoogleTest()

描述：初始化 GoogleTest。在调用 RUN_ALL_TESTS() 之前必须调用此函数。特别是，它解析 GoogleTest 识别的命令行标志。每当看到 GoogleTest 标志时，它会从 argv 中移除该标志，并递减 *argc。请记住，argv 必须以 NULL 指针终止（即 argv[argc] 是 NULL），这已经是传递给 main 的默认 argv 的情况。

返回值：不返回任何值。相反，GoogleTest 标志变量会被更新。

重载版本：

• InitGoogleTest(int* argc, wchar_t** argv) 重载可用于在 UNICODE 模式下编译的 Windows 程序。
• 无参数的 InitGoogleTest() 重载可用于 Arduino/嵌入式平台，这些平台没有 argc/argv。

4.2 AddGlobalTestEnvironment

Environment* testing::AddGlobalTestEnvironment(Environment* env)

描述：向测试程序添加一个测试环境。必须在调用 RUN_ALL_TESTS() 之前调用。请参阅全局设置和清理以获取更多信息。

相关类：请参阅 Environment。

4.3 RegisterTest

template <typename Factory>
TestInfo* testing::RegisterTest(const char* test_suite_name, const char* test_name,
                                const char* type_param, const char* value_param,
                                const char* file, int line, Factory factory)

描述：动态地向框架注册一个测试。

参数说明：

• factory 参数是一个工厂可调用对象（可移动构造）或函数指针，用于创建 Test 对象的新实例。它将所有权交给调用者。该可调用对象的签名是 Fixture*()，其中 Fixture 是测试的测试夹具类。所有使用相同 test_suite_name 注册的测试必须返回相同的夹具类型。此检查在运行时进行。

框架行为：

• 框架将从工厂推导夹具类，并为其调用 SetUpTestSuite 和 TearDownTestSuite 方法。

调用时机：

• 必须在调用 RUN_ALL_TESTS() 之前调用，否则行为是未定义的。

相关函数：请参阅程序化注册测试。

4.4 RUN_ALL_TESTS

int RUN_ALL_TESTS()

描述：在 main() 中使用此函数运行所有测试。如果所有测试都成功，则返回 0，否则返回 1。

调用时机：

• RUN_ALL_TESTS() 应该在命令行被 InitGoogleTest() 解析之后调用。

历史说明：

• 此函数以前是一个宏；因此，它位于全局命名空间中，并且名称全部为大写。

4.5 AssertionSuccess

AssertionResult testing::AssertionSuccess()

描述：创建一个成功的断言结果。请参阅 AssertionResult。

4.6 AssertionFailure

AssertionResult testing::AssertionFailure()

testing::AssertionFailure()：创建一个失败的断言结果。可以使用 << 运算符来存储失败消息：

testing::AssertionFailure() << "我的失败消息";

详见 AssertionResult。

4.7 StaticAssertTypeEq

testing::StaticAssertTypeEq<T1, T2>()：用于类型相等的编译时断言。仅当 T1 和 T2 是相同类型时才会编译通过。它返回的值无关紧要。

详见类型断言相关内容。

4.8 PrintToString

std::string testing::PrintToString(x)：使用 GoogleTest 的值打印机打印任意值 x。

详见“教 GoogleTest 如何打印你的值”相关内容。

4.9 PrintToStringParamName

std::string testing::PrintToStringParamName(TestParamInfo<T>& info)：这是一个内置的参数化测试名称生成器，返回对 info.param 调用 PrintToString 的结果。当测试参数是 std::string 或 C 字符串时，它不起作用。

详见“为值参数化测试参数指定名称”相关内容。

另外，还可参考 TestParamInfo 和 INSTANTIATE_TEST_SUITE_P。xxxxxxxxxx INSTANTIATE_TEST_SUITE_P(MyInstantiation, MyTestSuite,    ConvertGenerator(Values(std::string(“s”)), [](std::string_view s) { … }));cpp