| hardly | b1e7e14 | 2014-08-06 00:43:51 +0300 | [diff] [blame] | 1 | <!DOCTYPE html>
|
| 2 | <html>
|
| 3 | <title>readme</title>
|
| 4 | <xmp theme="united" style="display:none;">
|
| 5 |
|
| 6 | doctest
|
| 7 | =======
|
| 8 |
|
| 9 | doctest is a c++ header only library for writing tests that is inspired by the unittest functionality in the D programming language and the docstrings in python - tests are documentation and should reside near the code they test.
|
| 10 |
|
| 11 | The library has automatic test discovery and is c++98 compatible.
|
| 12 |
|
| 13 | Tests are registered with the following macros:
|
| 14 |
|
| 15 | - doctest(test_name) {}
|
| 16 | - doctest_noname {}
|
| 17 | - doctest_fixture(fixture_class, test_name) {}
|
| 18 | - doctest_fixture_noname(fixture_class) {}
|
| 19 | - doctest_static_method(class_name, method_name)
|
| 20 |
|
| 21 | Tests can be registered anywhere - from source to header files. Each test is guaranteed to be registered only once no matter how many occurances it has in the code.
|
| 22 |
|
| 23 | To register a static method of a class as a test the user should use the doctest_static_method() macro outside of the class definition.
|
| 24 | The method should be of type ```void(*)(void)```. Such tests cannot be named. See the **class_static_method** example.
|
| 25 |
|
| 26 | To invoke all the registered tests call DOCTEST_INVOKE_ALL_TEST_FUNCTIONS() passing the argc and argv of the program like this:
|
| 27 | ```
|
| 28 | DOCTEST_INVOKE_ALL_TEST_FUNCTIONS(argc, argv);
|
| 29 | ```
|
| 30 |
|
| 31 | ##Test naming
|
| 32 |
|
| 33 | Tests can be invoked based on filter strings (comma separated on the command line). Names are case sensitive.
|
| 34 | Tests registered without a name actually have an empty name ("") and are invoked only when no filters are supplied.
|
| 35 |
|
| 36 | For more information about the command line go [here](command_line.html)
|
| 37 |
|
| 38 | ```
|
| 39 | #include <iostream>
|
| 40 | using namespace std;
|
| 41 |
|
| 42 | doctest(Test1) { cout << "Test1" << endl; }
|
| 43 | doctest(Test2) { cout << "Test2" << endl; }
|
| 44 | doctest(Test3) { cout << "Test3" << endl; }
|
| 45 | doctest(Test_asd) { cout << "Test_asd" << endl; }
|
| 46 | doctest(Test_asd2) { cout << "Test_asd2" << endl; }
|
| 47 | doctest(Test_asd2) { cout << "Test_asd2 (copy)" << endl; }
|
| 48 | doctest(Test_asd2) { cout << "Test_asd2 (copy 2)" << endl; }
|
| 49 | ```
|
| 50 |
|
| 51 | For the above tests when we call the program with these args
|
| 52 |
|
| 53 | ```
|
| 54 | ./exe -doctest=asd2,Test2
|
| 55 | ```
|
| 56 |
|
| 57 | the output will be this:
|
| 58 |
|
| 59 | ```
|
| 60 | Test_asd2
|
| 61 | Test_asd2 (copy)
|
| 62 | Test_asd2 (copy 2)
|
| 63 | Test2
|
| 64 | ```
|
| 65 |
|
| 66 | ##Fixtures
|
| 67 |
|
| 68 | Fixtures are supported - they are basically a normal class. To have access to the data members of a fixture class they should be public or protected. Each test using a fixture will have it's fixture initialized for it. Fixture classes may also inherit each other to form more complex hierarchies.
|
| 69 |
|
| 70 | ```
|
| 71 | #include <iostream>
|
| 72 | using namespace std;
|
| 73 |
|
| 74 | struct Shared {
|
| 75 | Shared() : a(5) { cout << "hello! I am a fixture ctor!" << endl; }
|
| 76 | ~Shared() { cout << "dtor-ing...!" << endl; }
|
| 77 | int a;
|
| 78 | };
|
| 79 |
|
| 80 | doctest_fixture(Shared, Fixture1_name) {
|
| 81 | cout << a << endl;
|
| 82 | a = 6;
|
| 83 | cout << a << endl;
|
| 84 | }
|
| 85 |
|
| 86 | doctest_fixture(Shared, Fixture2_name) {
|
| 87 | cout << a << endl;
|
| 88 | a = 8;
|
| 89 | cout << a << endl;
|
| 90 | }
|
| 91 |
|
| 92 | doctest_fixture_noname(Shared) {
|
| 93 | cout << a << endl;
|
| 94 | a = 2;
|
| 95 | cout << a << endl;
|
| 96 | }
|
| 97 | ```
|
| 98 |
|
| 99 | For the above tests the output will be this:
|
| 100 |
|
| 101 | ```
|
| 102 | hello! I am a fixture ctor!
|
| 103 | 5
|
| 104 | 6
|
| 105 | dtor-ing...!
|
| 106 | hello! I am a fixture ctor!
|
| 107 | 5
|
| 108 | 8
|
| 109 | dtor-ing...!
|
| 110 | hello! I am a fixture ctor!
|
| 111 | 5
|
| 112 | 2
|
| 113 | dtor-ing...!
|
| 114 | ```
|
| 115 |
|
| 116 | ##Notes
|
| 117 |
|
| 118 | - The library does not produce any warnings with GCC when compiled with ```-Wall -Wextra -pedantic -std=c++98 -m64```
|
| 119 |
|
| 120 | - The registration of test functions can be disabled by defining ```DOCTEST_GLOBAL_DISABLE``` before the inclusion of the **doctest.h** header. For large projects with tens of thousands of tests this may reduce the link time of the production build especially if lots of tests are registered in header files and will also reduce the binary size. See **disabled** from the examples folder.
|
| 121 |
|
| 122 | - The library by default includes its implementation which drags a dependency on **std::map**, the **cstring** header and the implementation of the library. This can be avoided by defining ```DOCTEST_DONT_INCLUDE_IMPLEMENTATION``` before the inclusion of **doctest.h** but then the user should include **doctest_impl.h** in one of his source files and have the ```DOCTEST_DONT_INCLUDE_IMPLEMENTATION``` macro defined before that as well. See **alternative_header_inclusion** from the examples folder.
|
| 123 |
|
| 124 | - Tests are registered from top to bottom of each processed cpp after the headers have been preprocessed and included but there is no ordering between cpp files.
|
| 125 |
|
| 126 | - Tests are registered globally within each shared object/executable. If a test is defined in a header and that header is used in an executable and in a shared object, then the test is registered in both places. To see how to invoke tests from a shared object check out **multi_dll** from the examples folder.
|
| 127 |
|
| 128 | - The library does not use operator new/delete (only malloc) so it's memory usage is completely transparent to the user and that makes it fit for testing even memory management.
|
| 129 |
|
| 130 | - For tests written on the same line only the first one will be registered successfully.
|
| 131 |
|
| 132 | - The only non-standard features used in this library are:
|
| 133 |
|
| 134 | - the **__COUNTER__** macro, but all major compilers support it (if it is not found, **__LINE__** is used and then there are some corner cases with the macro codegen and a test may be registered twice)
|
| 135 |
|
| 136 | - the **pragma once** directive - supporting the DRY principle
|
| 137 |
|
| 138 | ##Workflow with examples
|
| 139 |
|
| 140 | The requirements for the examples are to have CMake 2.8 or higher.
|
| 141 |
|
| 142 | ####Under Linux
|
| 143 |
|
| 144 | To build an example navigate to its folder and enter
|
| 145 |
|
| 146 | ```
|
| 147 | cmake ./
|
| 148 | make
|
| 149 | ./exe
|
| 150 | ```
|
| 151 |
|
| 152 | ####Under Windows
|
| 153 |
|
| 154 | You will need **MinGW w64** installed for Windows (or MSVC 2013 - hardcoded in the .bat files)
|
| 155 |
|
| 156 | You can get **MinGW w64** from http://sourceforge.net/projects/mingwbuilds/ (arch: "x64" threads: "posix" exceptions: "seh")
|
| 157 |
|
| 158 | Use the bat files in the examples folder to build (or atleast configure) each example - place them in the sub folder of an example and run them
|
| 159 |
|
| 160 | - **g.bat** - generates build files through cmake
|
| 161 |
|
| 162 | - **c.bat** - invokes mingw32-make on the makefile target
|
| 163 |
|
| 164 | - **r.bat** - runs the exe
|
| 165 |
|
| 166 |
|
| 167 | </xmp>
|
| 168 | <script src="strapdown.js/strapdown.js"></script>
|
| 169 | </html>
|