[Documentation suggestion] Provide executable examples and link to them
- 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
Assessment
This issue has not been assessed yet.