catchorg / catchorg/Catch2

[Documentation suggestion] Provide executable examples and link to them

Open
#1,037 7 comments 1 reaction 0 assignees View on GitHub
Documentation
Dominant language
C++
Stars
21.5k
Forks
3.5k
Avg merge
3d 16h
Merged PRs (30d)
2

Description

Readers of Catch' documentation may benefit from readily available, complete and executable examples that show a limited and coherent set of features and steps needed for compilation. The tutorial and reference documentation can then link to relevant examples that the reader can [try, perhaps even online](https://wandbox.org/permlink/qf7pR9ZXm16W3r4H).

Compilation of these examples must be integrated with the continuous integration process. As such the examples become [executable documentation](https://accu.org/index.php/journals/1871) geared towards the user.

For example:
```
// Assertions

// Compile:
// - g++ -I$(CATCH_SINGLE_INCLUDE) -o assertions assertions.cpp && assertions --success
// - cl -EHsc -I%CATCH_SINGLE_INCLUDE% assertions.cpp && assertions --success

// Let Catch provide main():
#define CATCH_CONFIG_MAIN

#include "catch.hpp"

std::string one() {
return "1";
}

TEST_CASE( "Assert that something is true (pass)", "[require]" ) {
REQUIRE( one() == "1" );
}

TEST_CASE( "Assert that something is true (fail)", "[require]" ) {
REQUIRE( one() == "x" );
}

TEST_CASE( "Assert that something is true (stop at first failure)", "[require]" ) {
REQUIRE( one() == "x" );
REQUIRE( one() == "1" );
}

TEST_CASE( "Assert that something is true (continue after failure)", "[check]" ) {
CHECK( one() == "x" );
REQUIRE( one() == "1" );
}
```

Subjects that come to mind:
- test case (test_case)
- assertions (require, check)
- exceptions (require_nothrow, require_throws, require_throws_as, require_throws_with, require_throws_matches)
- matchers (require_that)
- floating point (approx)
- logging (capture, info, warn, fail, succeed, fail_check)
- fixtures (test_case_method)
- sections
- bdd (scenario, given, when, then, and_when, and_then)
- string conversions
- reporters
- event listeners
- supplying your own main()
- compile-time configuration

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.