[Documentation suggestion] Provide executable examples and link to them

[martinmoene]

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.

Compilation of these examples must be integrated with the continuous integration process. As such the examples become executable documentation 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

[horenmar]

Basically, you want parts of SelfTest to become self-contained and hosted on Wandbox or similar, correct?

[martinmoene]

Indeed, with the difference that SelfTest may be geared (too much) towards implementers, complete and overwhelming where mere users may need another approach to support their understanding.

Key:

• relatively simple
• complete program
• that compiles and executes and shows what's necessary for that
• perhaps shows the expected output
• and is at the tip if reader's fingers from the documentation

See for example the examples linked from section Usage of lest.

[horenmar]

Yeah, SelfTest's primary aim is to (mostly) guarantee that things didn't get broken by a change, secondary aim is a reference for someone who already knows Catch well and documentation for newbies is a very distant third.

Anyway, I can see some value in adding these, but honestly don't have much time (and what little I do, I'd like to use for different things), so this will likely either get put on a backburner, or someone else needs to put in a PR (hint, hint).

[martinmoene]

I can see some value in adding these

is what I liked to know ;)

[martinmoene]

Plan (in progress):

Overall, part 1:

• [x] Create branch examples
• [x] Create folder examples
• [x] Create several examples to get the gist, see below
• [x] Add a page 'List of examples' (doc/list-of-examples.md)
• [x] Link to examples from Tutorial
• [x] Publish branch for review feedback
• [x] Integrate with CMake
• [x] Integrate with CI: Travis (linux/gcc7: no_selftest, build_examples)
• [x] Integrate with CI: AppVeyor

Overall, part 2 (in progress):

• [ ] Link to examples from Reference
• [ ] ...

Examples, part 1:

• [x] 000-CatchMain.cpp, Catch-provided main
• [x] 010-TestCase.cpp, single file
• [x] 020-TestCase,-*.cpp multiple files 1, 2
• [x] 030-Asn-Require-Check.cpp
• [x] 100-Fix-Section.cpp
• [x] 110-Fix-ClassFixture.cpp
• [x] 120-Bdd-ScenarioGivenWhenThen.cpp
• [x] 210-Evt-EventListeners.cpp

Examples, part 2 (in progress):

• [x] 200-Rpt-CatchMain.cpp, Catch-provided main
• [x] 207-Rpt-TeamCityReporter.cpp

Examples, rest:

• [ ] 040-Asn-RequireThat.cpp
• [ ] 050-Asn-RequireNoThrow.cpp
• [ ] 050-Asn-RequireThrows.cpp
• [ ] 070-Asn-RequireThrowsAs.cpp
• [ ] 080-Asn-RequireThrowsWith.cpp
• [ ] 090-Asn-RequireThrowsMatches.cpp
• [ ] 130-Fpt-Approx.cpp
• [ ] 140-Log-Capture.cpp
• [ ] 150-Log-Info.cpp
• [ ] 160-Log-Warn.cpp
• [ ] 170-Log-Fail-Check.cpp
• [ ] 180-Log-Succeed.cpp
• [ ] 190-Rpt-ReportUserDefinedType.cpp
• [ ] 202-Rpt-UserDefinedReporter.cpp
• [ ] 205-Rpt-AutomakeReporter.cpp
• [ ] 206-Rpt-TapReporter.cpp
• [ ] 208-Rpt-MultipleReporters.cpp
• [ ] 220-Cfg-OwnMain.cpp
• [ ] 230-Cfg-CompileTimeConfiguration.cpp
• [ ] 240-Cfg-RunTimeConfiguration.cpp

[ahadji05]

I installed the Catch2 framework using the CMake installation and when I try to compile and run any example I get this error: CATCH_SINGLE_INCLUDE: command not found

this is how I compile an example: $ g++ -std=c++11 -Wall -I$(CATCH_SINGLE_INCLUDE) -c 000-CatchMain.cpp

what is the purpose of the macro CATCH_SINGLE_INCLUDE ?

[horenmar]

@ahadji05 It should contain path to the single-include version of catch.hpp.