diff options
| author | matthew-limbinar | 2021-03-23 07:20:33 -0400 |
|---|---|---|
| committer | GitHub | 2021-03-23 12:20:33 +0100 |
| commit | 6734c0aa643a58ff7daaa005bb4ce79c67e43cfc (patch) | |
| tree | 7ef85cd6e62e8583058433b93217c61910c93a5b /docs/test-cases-and-sections.md | |
| parent | 037ddbc75cc5e58b93cf5a010a94b32333ad824d (diff) | |
| download | catch3-6734c0aa643a58ff7daaa005bb4ce79c67e43cfc.tar.gz | |
Expand documentation for BDD test macros (#2179)
Diffstat (limited to 'docs/test-cases-and-sections.md')
| -rw-r--r-- | docs/test-cases-and-sections.md | 41 |
1 files changed, 39 insertions, 2 deletions
diff --git a/docs/test-cases-and-sections.md b/docs/test-cases-and-sections.md index 5943acf0..4899af0e 100644 --- a/docs/test-cases-and-sections.md +++ b/docs/test-cases-and-sections.md @@ -90,13 +90,50 @@ This macro maps onto ```TEST_CASE``` and works in the same way, except that the * **WHEN(** _something_ **)** * **THEN(** _something_ **)** -These macros map onto ```SECTION```s except that the section names are the _something_s prefixed by "given: ", "when: " or "then: " respectively. +These macros map onto ```SECTION```s except that the section names are the _something_ texts prefixed by +"given: ", "when: " or "then: " respectively. These macros also map onto the AAA or A<sup>3</sup> test pattern +(standing either for [Assemble-Activate-Assert](http://wiki.c2.com/?AssembleActivateAssert) or +[Arrange-Act-Assert](http://wiki.c2.com/?ArrangeActAssert)), and in this context, the macros provide both code +documentation and reporting of these parts of a test case without the need for extra comments or code to do so. + +Semantically, a `GIVEN` clause may have multiple _independent_ `WHEN` clauses within it. This allows a test +to have, e.g., one set of "given" objects and multiple subtests using those objects in various ways in each +of the `WHEN` clauses without repeating the initialisation from the `GIVEN` clause. When there are _dependent_ +clauses -- such as a second `WHEN` clause that should only happen _after_ the previous `WHEN` clause has been +executed and validated -- there are additional macros starting with `AND_`: * **AND_GIVEN(** _something_ **)** * **AND_WHEN(** _something_ **)** * **AND_THEN(** _something_ **)** -Similar to ```GIVEN```, ```WHEN``` and ```THEN``` except that the prefixes start with "and ". These are used to chain ```GIVEN```s, ```WHEN```s and ```THEN```s together. +These are used to chain ```GIVEN```s, ```WHEN```s and ```THEN```s together. The `AND_*` clause is placed +_inside_ the clause on which it depends. There can be multiple _independent_ clauses that are all _dependent_ +on a single outer clause. +```cpp +SCENARIO( "vector can be sized and resized" ) { + GIVEN( "An empty vector" ) { + auto v = std::vector<std::string>{}; + + // Validate assumption of the GIVEN clause + THEN( "The size and capacity start at 0" ) { + REQUIRE( v.size() == 0 ); + REQUIRE( v.capacity() == 0 ); + } + + // Validate one use case for the GIVEN object + WHEN( "push_back() is called" ) { + v.push_back("hullo"); + + THEN( "The size changes" ) { + REQUIRE( v.size() == 1 ); + REQUIRE( v.capacity() >= 1 ); + } + } + } +} +``` +See [this working example](https://godbolt.org/z/e5vPPM), with an intentional failure to demonstrate the reporting +output. > `AND_GIVEN` was [introduced](https://github.com/catchorg/Catch2/issues/1360) in Catch2 2.4.0. |