Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 935e52ceadb96f6425799f10304a3fa9724958e9 / . / doc / html_generated / testcases.html
blob: 25b260a61d061bff15600a54f59fa84361059f77 [file] [log] [blame]
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]1<!DOCTYPE html>
2<html>
3<title>testcases</title>
4<xmp theme="united" style="display:none;">
5
6## Test cases
7
onqtam935e52c2019-02-10 13:37:42 +0200[diff] [blame^]8While **doctest** fully supports the traditional, xUnit, style of class-based fixtures containing test case methods this is not the preferred style. Instead **doctest** provides a powerful mechanism for nesting subcases within a test case. For a more detailed discussion and examples see the [**tutorial**](tutorial.html#test-cases-and-subcases).
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]9
10Test cases and subcases are very easy to use in practice:
11
12* **TEST_CASE(** _test name_ **)**
13* **SUBCASE(** _subcase name_ **)**
14
15_test name_ and _subcase name_ are free form, quoted, strings. Test names don't have to be unique within the **doctest** executable. They should also be string literals.
16
onqtam935e52c2019-02-10 13:37:42 +0200[diff] [blame^]17It is possible to write test cases inside of class bodies in C++17 with the help of ```TEST_CASE_CLASS()``` - used just like ```TEST_CASE()``` - making testing private parts of classes easier.
18
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]19Keep in mind that even though **doctest** is [**thread-safe**](faq.html#is-doctest-thread-aware) - using subcases has to be done only in the main test runner thread.
20
onqtam935e52c2019-02-10 13:37:42 +0200[diff] [blame^]21Test cases can also be parameterized - see the [**documentation**](parameterized-tests.html)
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]22
23Test cases and subcases can be filtered through the use of the [**command line**](commandline.html)
24
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]25## BDD-style test cases
26
27In addition to **doctest**'s take on the classic style of test cases, **doctest** supports an alternative syntax that allow tests to be written as "executable specifications" (one of the early goals of [Behaviour Driven Development](http://dannorth.net/introducing-bdd/)). This set of macros map on to ```TEST_CASE```s and ```SUBCASE```s, with a little internal support to make them smoother to work with.
28
29* **SCENARIO(** _scenario name_ **)**
30
31This macro maps onto ```TEST_CASE``` and works in the same way, except that the test case name will be prefixed by "Scenario: "
32
onqtam6a5da422017-09-04 17:56:08 +0300[diff] [blame]33* **SCENARIO_TEMPLATE(** _scenario name_, _type_, _list of types_ **)**
34
35This macro maps onto ```TEST_CASE_TEMPLATE``` and works in the same way, except that the test case name will be prefixed by "Scenario: "
36
37* **SCENARIO_TEMPLATE_DEFINE(** _scenario name_, _type_, _id_ **)**
38
39This macro maps onto ```TEST_CASE_TEMPLATE_DEFINE``` and works in the same way, except that the test case name will be prefixed by "Scenario: "
40
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]41* **GIVEN(** _something_ **)**
42* **WHEN(** _something_ **)**
43* **THEN(** _something_ **)**
44
45These macros map onto ```SUBCASE```s except that the subcase names are the _something_s prefixed by "given: ", "when: " or "then: " respectively.
46
47* **AND_WHEN(** _something_ **)**
48* **AND_THEN(** _something_ **)**
49
50Similar to ```WHEN``` and ```THEN``` except that the prefixes start with "and ". These are used to chain ```WHEN```s and ```THEN```s together.
51
52When any of these macros are used the console reporter recognises them and formats the test case header such that the Givens, Whens and Thens are aligned to aid readability.
53
54Other than the additional prefixes and the formatting in the console reporter these macros behave exactly as ```TEST_CASE```s and ```SUBCASE```s. As such there is nothing enforcing the correct sequencing of these macros - that's up to the programmer!
55
56## Test fixtures
57
58Although **doctest** allows you to group tests together as subcases within a test case, it can still be convenient, sometimes, to group them using a more traditional test fixture. **doctest** fully supports this too. You define the test fixture as a simple structure:
59
60```
61class UniqueTestsFixture {
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]62private:
63 static int uniqueID;
64protected:
65 DBConnection conn;
66public:
67 UniqueTestsFixture() : conn(DBConnection::createConnection("myDB")) {}
68protected:
69 int getID() {
70 return ++uniqueID;
71 }
72};
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]73
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]74int UniqueTestsFixture::uniqueID = 0;
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]75
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]76TEST_CASE_FIXTURE(UniqueTestsFixture, "Create Employee/No Name") {
77 REQUIRE_THROWS(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), ""));
78}
79TEST_CASE_FIXTURE(UniqueTestsFixture, "Create Employee/Normal") {
80 REQUIRE(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), "Joe Bloggs"));
81}
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]82```
83
84The two test cases here will create uniquely-named derived classes of UniqueTestsFixture and thus can access the `getID()` protected method and `conn` member variables. This ensures that both the test cases are able to create a DBConnection using the same method (DRY principle) and that any ID's created are unique such that the order that tests are executed does not matter.
85
86## Test suites
87
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]88Test cases can be grouped into test suites. This is done with ```TEST_SUITE()``` or ```TEST_SUITE_BEGIN()``` / ```TEST_SUITE_END()```.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]89
90For example:
91
92```
93TEST_CASE("") {} // not part of any test suite
94
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]95TEST_SUITE("math") {
96 TEST_CASE("") {} // part of the math test suite
97 TEST_CASE("") {} // part of the math test suite
98}
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]99
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]100TEST_SUITE_BEGIN("utils");
101
102TEST_CASE("") {} // part of the utils test suite
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]103
104TEST_SUITE_END();
105
106TEST_CASE("") {} // not part of any test suite
107```
108
109Then test cases from specific test suites can be executed with the help of filters - check out the [**command line**](commandline.html)
110
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]111## Decorators
112
113Test cases can be *decorated* with additional attributes like this:
114
115```
116TEST_CASE("name"
117 * doctest::description("shouldn't take more than 500ms")
118 * doctest::timeout(0.5)) {
119 // asserts
120}
121```
122
123Multiple decorators can be used at the same time. These are the currently supported decorators:
124
125- **```skip(bool = true)```** - marks the test case to be skipped from execution - unless the ```--no-skip``` option is used
126- **```may_fail(bool = true)```** - doesn't fail the test if any given assertion fails (but still reports it) - this can be useful to flag a work-in-progress, or a known issue that you don't want to immediately fix but still want to track in the your tests
onqtamc80eed12017-10-06 11:01:05 +0300[diff] [blame]127- **```should_fail(bool = true)```** - like **```may_fail()```** but fails the test if it passes - his can be useful if you want to be notified of accidental, or third-party, fixes
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]128- **```expected_failures(int)```** - defines the number of assertions that are expected to fail within the test case - reported as failure when the number of failed assertions is different than the declared expected number of failures
129- **```timeout(double)```** - fails the test case if its execution exceeds this limit (in seconds) - but doesn't terminate it - that would require subprocess support
130- **```test_suite("name")```** - can be used on test cases to override (or just set) the test suite they are in
131- **```description("text")```** - a description of the test case
132
133The values that the decorators take are computed while registering the test cases (during global initialization) - before entering ```main()``` and not just before running them.
134
135Decorators can also be applied to test suite blocks and all test cases in that block inherit them:
136
137```
138TEST_SUITE("some TS" * doctest::description("all tests will have this")) {
139 TEST_CASE("has a description from the surrounding test suite") {
140 // asserts
141 }
142}
143TEST_SUITE("some TS") {
144 TEST_CASE("no description even though in the same test suite as the one above") {
145 // asserts
146 }
147}
148```
149
150Test cases can override the decorators that they inherit from their surrounding test suite:
151
152```
153TEST_SUITE("not longer than 500ms" * doctest::timeout(0.5)) {
154 TEST_CASE("500ms limit") {
155 // asserts
156 }
157 TEST_CASE("200ms limit" * doctest::timeout(0.2)) {
158 // asserts
159 }
160}
161```
162
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]163------
164
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]165- Check out the [**subcases and BDD example**](../../examples/all_features/subcases.cpp)
166- Check out the [**assertion macros example**](../../examples/all_features/assertion_macros.cpp) to see how test suites are used
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]167- 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.
168
169---------------
170
171[Home](readme.html#reference)
172
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]173<p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p>
174
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]175
176</xmp>
177<script src="strapdown.js/strapdown.js"></script>
178</html>