From 9d4cde44a4a3952cf21861f9370b3bed9265dfd7 Mon Sep 17 00:00:00 2001
From: Gennadiy Civil <gennadiycivil@users.noreply.github.com>
Date: Mon, 13 May 2019 10:35:10 -0400
Subject: [PATCH] Added docs for testing::RegisterTest

---
 googletest/docs/advanced.md | 72 +++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/googletest/docs/advanced.md b/googletest/docs/advanced.md
index b1a4815e..16ff0812 100644
--- a/googletest/docs/advanced.md
+++ b/googletest/docs/advanced.md
@@ -1817,6 +1817,78 @@ For technical reasons, there are some caveats:
 1.  `statement` in `EXPECT_FATAL_FAILURE{_ON_ALL_THREADS}()()` cannot return a
     value.
 
+## Registering tests programmatically
+
+The `TEST` macros handle the vast majority of all use cases, but there are few
+were runtime registration logic is required. For those cases, the framework
+provides the `::testing::RegisterTest` that allows callers to register arbitrary
+tests dynamically.
+
+This is an advanced API only to be used when the `TEST` macros are insufficient.
+The macros should be preferred when possible, as they avoid most of the
+complexity of calling this function.
+
+It provides the following signature:
+
+```c++
+template <typename Factory>
+TestInfo* RegisterTest(const char* test_case_name, const char* test_name,
+                       const char* type_param, const char* value_param,
+                       const char* file, int line, Factory factory);
+```
+
+The `factory` argument is a factory callable (move-constructible) object or
+function pointer that creates a new instance of the Test object. It handles
+ownership to the caller. The signature of the callable is `Fixture*()`, where
+`Fixture` is the test fixture class for the test. All tests registered with the
+same `test_case_name` must return the same fixture type. This is checked at
+runtime.
+
+The framework will infer the fixture class from the factory and will call the
+`SetUpTestCase` and `TearDownTestCase` for it.
+
+Must be called before `RUN_ALL_TESTS()` is invoked, otherwise behavior is
+undefined.
+
+Use case example:
+
+```c++
+class MyFixture : public ::testing::Test {
+ public:
+  // All of these optional, just like in regular macro usage.
+  static void SetUpTestCase() { ... }
+  static void TearDownTestCase() { ... }
+  void SetUp() override { ... }
+  void TearDown() override { ... }
+};
+
+class MyTest : public MyFixture {
+ public:
+  explicit MyTest(int data) : data_(data) {}
+  void TestBody() override { ... }
+
+ private:
+  int data_;
+};
+
+void RegisterMyTests(const std::vector<int>& values) {
+  for (int v : values) {
+    ::testing::RegisterTest(
+        "MyFixture", ("Test" + std::to_string(v)).c_str(), nullptr,
+        std::to_string(v).c_str(),
+        __FILE__, __LINE__,
+        // Important to use the fixture type as the return type here.
+        [=]() -> MyFixture* { return new MyTest(v); });
+  }
+}
+...
+int main(int argc, char** argv) {
+  std::vector<int> values_to_test = LoadValuesFromConfig();
+  RegisterMyTests(values_to_test);
+  ...
+  return RUN_ALL_TESTS();
+}
+```
 
 ## Getting the Current Test's Name