From 34266b6e0fee3bb481f5549c91a3c8e0a0f8d69f Mon Sep 17 00:00:00 2001 From: Phil Nash Date: Wed, 2 Oct 2013 08:17:46 +0100 Subject: [PATCH] more doc formatting fixes --- docs/assertions.md | 35 +++++++++++++++++++-------------- docs/test-cases-and-sections.md | 16 +++++++-------- 2 files changed, 28 insertions(+), 23 deletions(-) diff --git a/docs/assertions.md b/docs/assertions.md index 3fe09be5..e72ee03f 100644 --- a/docs/assertions.md +++ b/docs/assertions.md @@ -1,6 +1,6 @@ # Assertion Macros -Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (_EQUALS, _NOTEQUALS, _GREATER_THAN etc). +Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (```_EQUALS```, ```_NOTEQUALS```, ```_GREATER_THAN``` etc). Catch is different. Because it decomposes natural C-style conditional expressions most of these forms are reduced to one or two that you will use all the time. That said there are a rich set of auxilliary macros as well. We'll describe all of these here. @@ -8,11 +8,12 @@ Most of these macros come in two forms: ## Natural Expressions -The REQUIRE family of macros tests an expression and aborts the test case if it fails. -The CHECK family are equivalent but execution continues in the same test case even if the assertion fails. This is useful if you have a series of essentially orthoginal assertions and it is useful to see all the results rather than stopping at the first failure. +The ```REQUIRE``` family of macros tests an expression and aborts the test case if it fails. +The ```CHECK``` family are equivalent but execution continues in the same test case even if the assertion fails. This is useful if you have a series of essentially orthoginal assertions and it is useful to see all the results rather than stopping at the first failure. + +* **REQUIRE(** _expression_ **)** and +* **CHECK(** _expression_ **)** -**REQUIRE(** _expression_ **)** and -**CHECK(** _expression_ **)** Evaluates the expression and records the result. If an exception is thrown it is caught, reported, and counted as a failure. These are the macros you will use most of the time Examples: @@ -22,8 +23,9 @@ CHECK( str == "string value" ); CHECK( thisReturnsTrue() ); REQUIRE( i == 42 ); ``` -**REQUIRE_FALSE(** _expression_ **)** and -**CHECK_FALSE(** _expression_ **)** +* **REQUIRE_FALSE(** _expression_ **)** and +* **CHECK_FALSE(** _expression_ **)** + Evaluates the expression and records the _logical NOT_ of the result. If an exception is thrown it is caught, reported, and counted as a failure. (these forms exist as a workaround for the fact that ! prefixed expressions cannot be decomposed). @@ -34,24 +36,27 @@ REQUIRE_FALSE( thisReturnsFalse() ); ## Exceptions -**REQUIRE_THROWS(** _expression_ **)** and -**CHECK_THROWS(** _expression_ **)** +* **REQUIRE_THROWS(** _expression_ **)** and +* **CHECK_THROWS(** _expression_ **)** + Expects that an exception (of any type) is be thrown during evaluation of the expression. -**REQUIRE_THROWS_AS(** _expression_ and _exception type_ **)** and -**CHECK_THROWS_AS(** _expression_, _exception type_ **)** +* **REQUIRE_THROWS_AS(** _expression_ and _exception type_ **)** and +* **CHECK_THROWS_AS(** _expression_, _exception type_ **)** + Expects that an exception of the _specified type_ is thrown during evaluation of the expression. -**REQUIRE_NOTHROW(** _expression_ **)** and -**CHECK_NOTHROW(** _expression_ **)** +* **REQUIRE_NOTHROW(** _expression_ **)** and +* **CHECK_NOTHROW(** _expression_ **)** + Expects that no exception is thrown during evaluation of the expression. ## Matcher expressions To support Matchers a slightly different form is used. Matchers will be more fully documented elsewhere. *Note that Matchers are still at early stage development and are subject to change.* -**REQUIRE_THAT(** _lhs_, _matcher call_ **)** and -**CHECK_THAT(** _lhs_, _matcher call_ **)** +* **REQUIRE_THAT(** _lhs_, _matcher call_ **)** and +* **CHECK_THAT(** _lhs_, _matcher call_ **)** --- diff --git a/docs/test-cases-and-sections.md b/docs/test-cases-and-sections.md index fe39c69b..4fc3f6f8 100644 --- a/docs/test-cases-and-sections.md +++ b/docs/test-cases-and-sections.md @@ -6,8 +6,8 @@ Instead Catch provides a powerful mechanism for nesting test case sections withi Test cases and sections are very easy to use in practice: -**TEST_CASE(** _test name_ \[**,** _tags_ \] **)** -**SECTION(** _section name_ **)** +* **TEST_CASE(** _test name_ \[, _tags_ \] **)** +* **SECTION(** _section name_ **)** _test name_ and _section name_ are free form, quoted, strings. The optional _tags_ argument is a quoted string containing one or more tags enclosed in square brackets. Tags are discussed below. Test names must be unique within the Catch executable. @@ -21,18 +21,18 @@ For examples see the [Tutorial](tutorial.md) In addition to Catch's take on the classic style of test cases, Catch 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 ```SECTION```s, with a little internal support to make them smoother to work with. -**SCENARIO(** _scenario name_ \[**,** _tags_ \] **)** +* **SCENARIO(** _scenario name_ \[, _tags_ \] **)** This macro maps onto ```TEST_CASE``` and works in the same way, except that the test case name will be prefixed by "Scenario: " -**GIVEN(** _something_ **)** -**WHEN(** _something_ **)** -**THEN(** _something_ **)** +* **GIVEN(** _something_ **)** +* **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. -**AND_WHEN(** _something_ **)** -**AND_THEN(** _something_ **)** +* **AND_WHEN(** _something_ **)** +* **AND_THEN(** _something_ **)** Similar to ```WHEN``` and ```THEN``` except that the prefixes start with "and ". These are used to chain ```WHEN```s and ```THEN```s together.