| onqtam | 8126b56 | 2016-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 | |
| 8 | While **doctest** fully supports the traditional, xUnit, style of class-based fixtures containing test case methods this is not the preferred style. |
| 9 | |
| 10 | Instead **doctest** provides a powerful mechanism for nesting subcases within a test case. For a more detailed discussion see the [**tutorial**](tutorial.html#test-cases-and-subcases). |
| 11 | |
| 12 | Test cases and subcases are very easy to use in practice: |
| 13 | |
| 14 | * **TEST_CASE(** _test name_ **)** |
| 15 | * **SUBCASE(** _subcase name_ **)** |
| 16 | |
| 17 | _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. |
| 18 | |
| 19 | For examples see the [Tutorial](tutorial.html) |
| 20 | |
| 21 | ## BDD-style test cases |
| 22 | |
| 23 | In 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. |
| 24 | |
| 25 | * **SCENARIO(** _scenario name_ **)** |
| 26 | |
| 27 | This macro maps onto ```TEST_CASE``` and works in the same way, except that the test case name will be prefixed by "Scenario: " |
| 28 | |
| 29 | * **GIVEN(** _something_ **)** |
| 30 | * **WHEN(** _something_ **)** |
| 31 | * **THEN(** _something_ **)** |
| 32 | |
| 33 | These macros map onto ```SUBCASE```s except that the subcase names are the _something_s prefixed by "given: ", "when: " or "then: " respectively. |
| 34 | |
| 35 | * **AND_WHEN(** _something_ **)** |
| 36 | * **AND_THEN(** _something_ **)** |
| 37 | |
| 38 | Similar to ```WHEN``` and ```THEN``` except that the prefixes start with "and ". These are used to chain ```WHEN```s and ```THEN```s together. |
| 39 | |
| 40 | When 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. |
| 41 | |
| 42 | Other 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! |
| 43 | |
| 44 | ## Test fixtures |
| 45 | |
| 46 | Although **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: |
| 47 | |
| 48 | ``` |
| 49 | class UniqueTestsFixture { |
| 50 | private: |
| 51 | static int uniqueID; |
| 52 | protected: |
| 53 | DBConnection conn; |
| 54 | public: |
| 55 | UniqueTestsFixture() : conn(DBConnection::createConnection("myDB")) { |
| 56 | } |
| 57 | protected: |
| 58 | int getID() { |
| 59 | return ++uniqueID; |
| 60 | } |
| 61 | }; |
| 62 | |
| 63 | int UniqueTestsFixture::uniqueID = 0; |
| 64 | |
| 65 | TEST_CASE_FIXTURE(UniqueTestsFixture, "Create Employee/No Name") { |
| 66 | REQUIRE_THROWS(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), "")); |
| 67 | } |
| 68 | TEST_CASE_METHOD(UniqueTestsFixture, "Create Employee/Normal") { |
| 69 | REQUIRE(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), "Joe Bloggs")); |
| 70 | } |
| 71 | ``` |
| 72 | |
| 73 | The 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. |
| 74 | |
| 75 | ## Test suites |
| 76 | |
| 77 | Test cases can be grouped into test suites. This is done with the ```TEST_SUITE()``` and ```TEST_SUITE_END()``` macros. |
| 78 | |
| 79 | For example: |
| 80 | |
| 81 | ``` |
| 82 | TEST_CASE("") {} // not part of any test suite |
| 83 | |
| 84 | TEST_SUITE("math"); |
| 85 | |
| 86 | TEST_CASE("") {} // part of the math test suite |
| 87 | TEST_CASE("") {} // part of the math test suite |
| 88 | |
| 89 | TEST_SUITE_END(); |
| 90 | |
| 91 | TEST_CASE("") {} // not part of any test suite |
| 92 | ``` |
| 93 | |
| 94 | Then test cases from specific test suites can be executed with the help of filters - check out the [**command line**](commandline.html) |
| 95 | |
| 96 | ------ |
| 97 | |
| 98 | - Check out the [**example**](../../examples/subcases_and_bdd/main.cpp) |
| 99 | - 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. |
| 100 | |
| 101 | --------------- |
| 102 | |
| 103 | [Home](readme.html#reference) |
| 104 | |
| 105 | |
| 106 | </xmp> |
| 107 | <script src="strapdown.js/strapdown.js"></script> |
| 108 | </html> |