d Add docs for doctest integration - see #11

Co-Authored-By: Llewellyn Falco <[email protected]>

ApprovalTests_DocTest_Tests/main.cpp

@@ -1,5 +1,5 @@
-// startcode doctest_main
+// begin-snippet: doctest_main
 // main.cpp:
 #define APPROVALS_DOCTEST // This tells Approval Tests to provide a main() - only do this in one cpp file
 #include "ApprovalTests.hpp"
-// endcode
+// end-snippet

README.md

@@ -47,6 +47,7 @@ Currently working in Mac/Linux/Windows with
 * [Catch2](https://github.com/catchorg/Catch2)   
 * [Okra](https://github.com/JayBazuzi/Okra) & C++ 11  
 * [GoogleTest](https://github.com/google/googletest)
+* [doctest](https://github.com/onqtam/doctest)
 
 
 
@@ -73,22 +74,13 @@ For catch (1 and 2), it's these two lines:
 <sup>[snippet source](/ApprovalTests_Catch2_Tests/main.cpp#L6-L10)</sup>
 <!-- endsnippet -->
 
-For Google Test, it's these:
-
-<!-- snippet: googletest_main -->
-```cpp
-// main.cpp:
-#define APPROVALS_GOOGLETEST // This tells Approval Tests to provide a main() - only do this in one cpp file
-#include "ApprovalTests.hpp"
-```
-<sup>[snippet source](/ApprovalTests_GoogleTest_Tests/main.cpp#L2-L6)</sup>
-<!-- endsnippet -->
-
 For all other test files, you need:
 ``` cpp
 #include "ApprovalTests.hpp"
 ```
 
+For other frameworks, check out our [Getting Started](/doc/GettingStarted.md#top) page. 
+
 ## Examples
 ApprovalTests uses ApprovalTests to test ApprovalTests (it's turtles all the way down).  
 [Checkout our own tests](https://github.com/approvals/ApprovalTests.cpp/tree/master/ApprovalTests_Catch2_Tests) to see how we do it.

doc/GettingStarted.md

@@ -16,6 +16,8 @@ To change this file edit the source file and then run MarkdownSnippets.
   * [Introduction](#introduction)
   * [Catch 1 and 2](#catch-1-and-2)
   * [Google Test](#google-test)
+  * [doctest](#doctest)
+  * [Choosing a testing framework](#choosing-a-testing-framework)
 <!-- endtoc -->
 
 
@@ -36,6 +38,22 @@ See [Getting Started With Catch 1 and 2](/doc/UsingCatch.md#getting-started-with
 
 See [Getting Started With Google Test](/doc/UsingGoogleTests.md#getting-started-with-google-test)
 
+## doctest
+
+See [Getting Started With doctest](/doc/UsingDoctest.md#getting-started-with-doctest)
+
+## Choosing a testing framework
+
+If you are already using one of the above testing frameworks, that is the one you should use.
+
+If not, Approval Tests works well with all the above. Here are factors to consider.
+
+| Framework | Ease of setup | IDE Integration | Compile and link time |
+| --- | --- | --- | --- |
+| Catch | Very easy (single-header). [StarterProject](https://github.com/approvals/ApprovalTests.Cpp.StarterProject) | Widely supported | Not bad - has options to speed up |
+| doctest | Very easy (single-header) | Unknown | Fast |
+| Google Test | Difficult (requires | Very widely supported | Fast |
+
 ---
 
 [Back to User Guide](/doc/README.md#top)

doc/UsingDoctest.md

@@ -0,0 +1,49 @@
+<!--
+GENERATED FILE - DO NOT EDIT
+This file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets).
+Source File: /doc/mdsource/UsingDoctest.source.md
+To change this file edit the source file and then run MarkdownSnippets.
+-->
+
+<a id="top"></a>
+
+# Using Approval Tests With doctest
+
+
+<!-- toc -->
+## Contents
+
+  * [Getting Started With doctest](#getting-started-with-doctest)
+    * [New Project](#new-project)
+<!-- endtoc -->
+
+
+
+
+## Getting Started With doctest
+
+The [doctest](https://github.com/onqtam/doctest) test framework works fairly well with Approval Tests.
+
+Doctest is similar to Catch, but claims to give faster compilation times.
+
+### New Project
+
+Create a file `main.cpp` and add just the following two lines:
+
+<!-- snippet: doctest_main -->
+```cpp
+// main.cpp:
+#define APPROVALS_DOCTEST // This tells Approval Tests to provide a main() - only do this in one cpp file
+#include "ApprovalTests.hpp"
+```
+<sup>[snippet source](/ApprovalTests_DocTest_Tests/main.cpp#L1-L5)</sup>
+<!-- endsnippet -->
+
+**Note**: currently, ApprovalTests overrides any `--reporter` command-line argument supplied.
+This is needed for ApprovalTests to function with doctest. The ApprovalTests reporter works like doctest's `console` reporter. This means that it is not possible to run ApprovalTests with the doctest test framework, and use reporters such as `xml`.
+
+We currently do not have a better workaround.
+
+---
+
+[Back to User Guide](/doc/README.md#top)

doc/mdsource/GettingStarted.source.md

@@ -22,6 +22,22 @@ See [Getting Started With Catch 1 and 2](/doc/UsingCatch.md#getting-started-with
 
 See [Getting Started With Google Test](/doc/UsingGoogleTests.md#getting-started-with-google-test)
 
+## doctest
+
+See [Getting Started With doctest](/doc/UsingDoctest.md#getting-started-with-doctest)
+
+## Choosing a testing framework
+
+If you are already using one of the above testing frameworks, that is the one you should use.
+
+If not, Approval Tests works well with all the above. Here are factors to consider.
+
+| Framework | Ease of setup | IDE Integration | Compile and link time |
+| --- | --- | --- | --- |
+| Catch | Very easy (single-header). [StarterProject](https://github.com/approvals/ApprovalTests.Cpp.StarterProject) | Widely supported | Not bad - has options to speed up |
+| doctest | Very easy (single-header) | Unknown | Fast |
+| Google Test | Difficult (requires | Very widely supported | Fast |
+
 ---
 
 [Back to User Guide](/doc/README.md#top)

doc/mdsource/UsingDoctest.source.md

@@ -0,0 +1,29 @@
+<a id="top"></a>
+
+# Using Approval Tests With doctest
+
+
+toc
+
+
+
+## Getting Started With doctest
+
+The [doctest](https://github.com/onqtam/doctest) test framework works fairly well with Approval Tests.
+
+Doctest is similar to Catch, but claims to give faster compilation times.
+
+### New Project
+
+Create a file `main.cpp` and add just the following two lines:
+
+snippet: doctest_main
+
+**Note**: currently, ApprovalTests overrides any `--reporter` command-line argument supplied.
+This is needed for ApprovalTests to function with doctest. The ApprovalTests reporter works like doctest's `console` reporter. This means that it is not possible to run ApprovalTests with the doctest test framework, and use reporters such as `xml`.
+
+We currently do not have a better workaround.
+
+---
+
+[Back to User Guide](/doc/README.md#top)

mdsource/README.source.md

@@ -30,6 +30,7 @@ Currently working in Mac/Linux/Windows with
 * [Catch2](https://github.com/catchorg/Catch2)   
 * [Okra](https://github.com/JayBazuzi/Okra) & C++ 11  
 * [GoogleTest](https://github.com/google/googletest)
+* [doctest](https://github.com/onqtam/doctest)
 
 
 
@@ -49,15 +50,13 @@ For catch (1 and 2), it's these two lines:
 
 snippet: catch_2_main
 
-For Google Test, it's these:
-
-snippet: googletest_main
-
 For all other test files, you need:
 ``` cpp
 #include "ApprovalTests.hpp"
 ```
 
+For other frameworks, check out our [Getting Started](/doc/GettingStarted.md#top) page. 
+
 ## Examples
 ApprovalTests uses ApprovalTests to test ApprovalTests (it's turtles all the way down).  
 [Checkout our own tests](https://github.com/approvals/ApprovalTests.cpp/tree/master/ApprovalTests_Catch2_Tests) to see how we do it.