Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Just some documentation. #2541

Open
wants to merge 2 commits into
base: devel
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
25 changes: 24 additions & 1 deletion docs/assertions.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@ Catch is different. Because it decomposes natural C-style conditional expression
Most of these macros come in two forms:

## Natural Expressions
```cpp
#include <catch2/catch_test_macros.hpp>
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this format for larger sections (ideally with their own headings) 👍


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 orthogonal assertions and it is useful to see all the results rather than stopping at the first failure.
Expand Down Expand Up @@ -50,6 +53,10 @@ REQUIRE_FALSE(ret); // ret must evaluate to false, and Catch2 will print
// out the value of ret if possibly
```

### Floating point comparisons
```cpp
#include <catch2/catch_approx.hpp>
```

### Other limitations

Expand Down Expand Up @@ -105,7 +112,9 @@ Expects that an exception of the _specified type_ is thrown during evaluation of

* **REQUIRE_THROWS_WITH(** _expression_, _string or string matcher_ **)** and
* **CHECK_THROWS_WITH(** _expression_, _string or string matcher_ **)**

```cpp
#include <catch2/matchers/catch_matchers.hpp>
```
Expects that an exception is thrown that, when converted to a string, matches the _string_ or _string matcher_ provided (see next section for Matchers).

e.g.
Expand Down Expand Up @@ -177,6 +186,20 @@ TEST_CASE_METHOD((Fixture<int, int>), "foo", "[bar]") {
This solution is not always applicable, because it might require extra
changes on the Catch's side to work.

## Lambdas
Lambdas are a C++ language feature and can be freely used inside a `TEST_CASE` or a `SECTION`.

```cpp
#include <catch2/catch_test_macros.hpp>

TEST_CASE("Dumb") {
auto fnTest = [](const bool bPass) { CHECK(bPass); };

fnTest(true);
}
```
[godbolt](https://catch2.godbolt.org/z/ebdr9vKcj)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This shows, but doesn't explain to non-experts, an important feature: the fact that assertions can happen outside the TEST_CASE.

There is also something interesting to be said about lambdas specifically: how do their capture lists behave across multiple invocations (due to SECTIONs).

So I would like to see a bit of text first explaining assertions in separate functions, then another piece about lambdas.

---

[Home](Readme.md#top)
3 changes: 3 additions & 0 deletions docs/benchmarks.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,9 @@ User code that cannot be executed repeatedly will lead to bogus results or
crashes.

## Benchmark specification
```cpp
#include <catch2/benchmark/catch_benchmark.hpp>
```

Benchmarks can be specified anywhere inside a Catch test case.
There is a simple and a slightly more advanced version of the `BENCHMARK` macro.
Expand Down
13 changes: 13 additions & 0 deletions docs/generators.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
# Data Generators

> Introduced in Catch2 2.6.0.
```cpp
#include <catch2/generators/catch_generators.hpp>
```

Data generators (also known as _data driven/parametrized test cases_)
let you reuse the same set of assertions across different input values.
Expand Down Expand Up @@ -145,6 +148,16 @@ type, making their usage much nicer. These are

> `range()` for floating point numbers has been introduced in Catch2 2.11.0

### Random generators
```cpp
#include <catch2/generators/catch_generators_random.hpp>
```

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But I don't like it for lists, and I don't like adding new sections just to have the include paths in them.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think there is enough extra information to be mentioned about the random generators (e.g. their repeatability guarantees) that this subheading could be filled out to be meaningful.

However, I don't see this also being true for the range generator, so we will need a different format for inline markings of things in lists.

### Range generators
```cpp
#include <catch2/generators/catch_generators_range.hpp>
```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because the text below now reads as part of the range generators.


And can be used as shown in the example below to create a generator
that returns 100 odd random number:

Expand Down
3 changes: 3 additions & 0 deletions docs/matchers.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ own and combine them with the Catch2-provided matchers seamlessly.


## Using Matchers
```cpp
#include <catch2/matchers/catch_matchers.hpp>
```

Matchers are most commonly used in tandem with the `REQUIRE_THAT` or
`CHECK_THAT` macros. The `REQUIRE_THAT` macro takes two arguments,
Expand Down