From f15b74c0d224c1b89fb2348b1c596227303f30c1 Mon Sep 17 00:00:00 2001 From: Phil Nash Date: Thu, 14 Nov 2013 19:08:19 +0000 Subject: [PATCH] Added some more docs --- docs/command-line.md | 2 +- docs/test-cases-and-sections.md | 17 +++++++- docs/tutorial.md | 77 ++++++++++++++++++++++++++++++++- 3 files changed, 93 insertions(+), 3 deletions(-) diff --git a/docs/command-line.md b/docs/command-line.md index b94dc86f..915286c8 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -21,7 +21,7 @@ Note that options are described according to the following pattern: Test cases, wildcarded test cases, tags and tag expressions are all passed directly as arguments. Tags are distinguished by being enclosed in square brackets. -If no test specs are supplied then all test cases, except "hidden" tests (tagged ```[hide]``` or, in the legacy case, prefixed by `'./'`) are run +If no test specs are supplied then all test cases, except "hidden" tests (tagged ```[hide]```, ```[.]``` or, in the legacy case, prefixed by `'./'`) are run. Specs must be enclosed in quotes if they contain spaces. If they do not contain spaces the quotes are optional. diff --git a/docs/test-cases-and-sections.md b/docs/test-cases-and-sections.md index 4fc3f6f8..863d5faf 100644 --- a/docs/test-cases-and-sections.md +++ b/docs/test-cases-and-sections.md @@ -15,7 +15,22 @@ For examples see the [Tutorial](tutorial.md) ## Tags --{placeholder for documentation of tags}- +Tags allow an arbitrary number of additional strings to be associated with a test case. Test cases can be selected (for running, or just for listing) by tag - or even by an expression that combines several tags. At their most basic level they provide a simple way to group several related tests together. + +As an example - given the following test cases: + + TEST_CASE( "A", "[widget]" ) { /* ... */ } + TEST_CASE( "B", "[widget]" ) { /* ... */ } + TEST_CASE( "C", "[gadget]" ) { /* ... */ } + TEST_CASE( "D", "[widget][gadget]" ) { /* ... */ } + +The tag expression, ```"[widget]"``` selects A, B & D. ```"[gadget]"``` selects C & D. ```"[widget][gadget]"``` selects just D and ```"[widget],[gadget]"``` selects all four test cases. + +For more detail on command line selection see [the command line docs](command-line.md#specifying-which-tests-to-run) + +A special tag name, ```[hide]``` causes test cases to be skipped from the default list (ie when no test cases have been explicitly selected through tag expressions or name wildcards). ```[.]``` is an alias for ```[hide]```. + +Tag names are not case sensitive. ## BDD-style test cases diff --git a/docs/tutorial.md b/docs/tutorial.md index 058167d4..2d75dab0 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -140,7 +140,82 @@ This works because the ```SECTION``` macro contains an if statement that calls b So far so good - this is already an improvement on the setup/ teardown approach because now we see our setup code inline and we can use the stack. --{placeholder for documentation on nested sections}- +The power of sections really shows, however, when we need to execute a sequence of, checked, operations. Continuing the vector example we might want to verify that after reserving a larger capacity, if we reserve smaller capacity (but still larger than the current size) then the capacity is not, in fact, changed. We can do that, naturally, like so: + + SECTION( "reserving bigger changes capacity but not size" ) { + v.reserve( 10 ); + + REQUIRE( v.size() == 5 ); + REQUIRE( v.capacity() >= 10 ); + + SECTION( "reserving smaller again does not change capacity" ) { + v.reserve( 7 ); + + REQUIRE( v.capacity() >= 10 ); + } + } + +Sections can be nested to an arbitrary depth (limited only by your stack size). Each leaf section (i.e. a section that contains no nested sections) will be executed exactly once, on a separate path of execution from any other leaf section (so no leaf section can interfere with another). Obviously a failure in a parent section will prevent nested sections from running - but that's the idea. + +## BDD-Style + +If you name your test cases and sections appropriately you can achieve a BDD-style specification structure. This became such a useful way of working that first class support has been added to Catch. Scenarios can be specified using ```SCENARIO```, ```GIVEN```, ```WHEN``` and ```THEN``` macros, which map on to ```TEST_CASE```s and ```SECTION```s, respectively (for more details see [Test cases and sections](test-cases-and-sections.md)). + +The vector example can be adjusted to use these macros like so: + +```c++ +SCENARIO( "vectors can be sized and resized", "[vector]" ) { + + GIVEN( "A vector with some items" ) { + std::vector v( 5 ); + + REQUIRE( v.size() == 5 ); + REQUIRE( v.capacity() >= 5 ); + + WHEN( "the size is increased" ) { + v.resize( 10 ); + + THEN( "the size and capacity change" ) { + REQUIRE( v.size() == 10 ); + REQUIRE( v.capacity() >= 10 ); + } + } + WHEN( "the size is reduced" ) { + v.resize( 0 ); + + THEN( "the size changes but not capacity" ) { + REQUIRE( v.size() == 0 ); + REQUIRE( v.capacity() >= 5 ); + } + } + WHEN( "more capacity is reserved" ) { + v.reserve( 10 ); + + THEN( "the capacity changes but not the size" ) { + REQUIRE( v.size() == 5 ); + REQUIRE( v.capacity() >= 10 ); + } + } + WHEN( "less capacity is reserved" ) { + v.reserve( 0 ); + + THEN( "neither size nor capacity are changed" ) { + REQUIRE( v.size() == 5 ); + REQUIRE( v.capacity() >= 5 ); + } + } + } +} +``` + +A nice consequence of this is that when these tests are run the test names are reported like this: + +``` +Scenario: vectors can be sized and resized + Given: A vector with some items + When: more capacity is reserved + Then: the capacity changes but not the size +``` ## Next steps For more specific information see the [Reference pages](reference-index.md)