Add MessageMatches matcher for exception (#2570)

docs/matchers.md

@@ -190,13 +190,21 @@ properties. The macro is `REQUIRE_THROWS_MATCHES(expr, ExceptionType, Matcher)`.
 > `REQUIRE_THROWS_MATCHES` macro lives in `catch2/matchers/catch_matchers.hpp`
 
 
-Catch2 currently provides only one matcher for exceptions,
-`Message(std::string message)`. `Message` checks that the exception's
+Catch2 currently provides two matchers for exceptions.
+These are:
+* `Message(std::string message)`.
+* `MessageMatches(Matcher matcher)`.
+
+`Message` checks that the exception's
 message, as returned from `what` is exactly equal to `message`.
 
+`MessageMatches` applies the provided matcher on the exception's
+message, as returned from `what`. This is useful in conjunctions with the `std::string` matchers (e.g. `StartsWith`)
+
 Example use:
 ```cpp
 REQUIRE_THROWS_MATCHES(throwsDerivedException(),  DerivedException,  Message("DerivedException::what"));
+REQUIRE_THROWS_MATCHES(throwsDerivedException(),  DerivedException,  MessageMatches(StartsWith("DerivedException")));
 ```
 
 Note that `DerivedException` in the example above has to derive from

src/catch2/matchers/catch_matchers_exception.hpp

@@ -29,6 +29,32 @@ class ExceptionMessageMatcher final : public MatcherBase<std::exception> {
 //! Creates a matcher that checks whether a std derived exception has the provided message
 ExceptionMessageMatcher Message(std::string const& message);
 
+template <typename StringMatcherType>
+class ExceptionMessageMatchesMatcher final
+    : public MatcherBase<std::exception> {
+    StringMatcherType m_matcher;
+
+public:
+    ExceptionMessageMatchesMatcher( StringMatcherType matcher ):
+        m_matcher( CATCH_MOVE( matcher ) ) {}
+
+    bool match( std::exception const& ex ) const override {
+        return m_matcher.match( ex.what() );
+    }
+
+    std::string describe() const override {
+        return " matches \"" + m_matcher.describe() + '"';
+    }
+};
+
+//! Creates a matcher that checks whether a message from an std derived
+//! exception matches a provided matcher
+template <typename StringMatcherType>
+ExceptionMessageMatchesMatcher<StringMatcherType>
+MessageMatches( StringMatcherType&& matcher ) {
+    return { CATCH_FORWARD( matcher ) };
+}
+
 } // namespace Matchers
 } // namespace Catch
 

tests/SelfTest/Baselines/automake.sw.approved.txt

@@ -142,6 +142,7 @@ Nor would this
 :test-result: PASS Exception as a value (e.g. in REQUIRE_THROWS_MATCHES) can be stringified
 :test-result: FAIL Exception matchers that fail
 :test-result: PASS Exception matchers that succeed
+:test-result: PASS Exception message can be matched
 :test-result: PASS Exception messages can be tested for
 :test-result: PASS Exceptions matchers
 :test-result: FAIL Expected exceptions that don't throw or unexpected exceptions fail the test

tests/SelfTest/Baselines/automake.sw.multi.approved.txt

@@ -140,6 +140,7 @@
 :test-result: PASS Exception as a value (e.g. in REQUIRE_THROWS_MATCHES) can be stringified
 :test-result: FAIL Exception matchers that fail
 :test-result: PASS Exception matchers that succeed
+:test-result: PASS Exception message can be matched
 :test-result: PASS Exception messages can be tested for
 :test-result: PASS Exceptions matchers
 :test-result: FAIL Expected exceptions that don't throw or unexpected exceptions fail the test

tests/SelfTest/Baselines/compact.sw.approved.txt

@@ -572,6 +572,10 @@ Matchers.tests.cpp:<line number>: failed: throwsSpecialException( 3 ), SpecialEx
 Matchers.tests.cpp:<line number>: failed: throwsSpecialException( 4 ), SpecialException, ExceptionMatcher{ 1 } for: SpecialException::what special exception has value of 1
 Matchers.tests.cpp:<line number>: passed: throwsSpecialException( 1 ), SpecialException, ExceptionMatcher{ 1 } for: SpecialException::what special exception has value of 1
 Matchers.tests.cpp:<line number>: passed: throwsSpecialException( 2 ), SpecialException, ExceptionMatcher{ 2 } for: SpecialException::what special exception has value of 2
+Matchers.tests.cpp:<line number>: passed: throwsDerivedException(), DerivedException, MessageMatches( StartsWith( "Derived" ) ) for: DerivedException::what  matches "starts with: "Derived""
+Matchers.tests.cpp:<line number>: passed: throwsDerivedException(), DerivedException, MessageMatches( EndsWith( "::what" ) ) for: DerivedException::what  matches "ends with: "::what""
+Matchers.tests.cpp:<line number>: passed: throwsDerivedException(), DerivedException, MessageMatches( !StartsWith( "::what" ) ) for: DerivedException::what  matches "not starts with: "::what""
+Matchers.tests.cpp:<line number>: passed: throwsSpecialException( 2 ), SpecialException, MessageMatches( StartsWith( "Special" ) ) for: SpecialException::what  matches "starts with: "Special""
 Exception.tests.cpp:<line number>: passed: thisThrows(), "expected exception" for: "expected exception" equals: "expected exception"
 Exception.tests.cpp:<line number>: passed: thisThrows(), Equals( "expecteD Exception", Catch::CaseSensitive::No ) for: "expected exception" equals: "expected exception" (case insensitive)
 Exception.tests.cpp:<line number>: passed: thisThrows(), StartsWith( "expected" ) for: "expected exception" starts with: "expected"
@@ -2459,7 +2463,7 @@ InternalBenchmark.tests.cpp:<line number>: passed: med == 18. for: 18.0 == 18.0
 InternalBenchmark.tests.cpp:<line number>: passed: q3 == 23. for: 23.0 == 23.0
 Misc.tests.cpp:<line number>: passed:
 Misc.tests.cpp:<line number>: passed:
-test cases:  394 |  304 passed |  83 failed |  7 failed as expected
-assertions: 2159 | 1989 passed | 143 failed | 27 failed as expected
+test cases:  395 |  305 passed |  83 failed |  7 failed as expected
+assertions: 2163 | 1993 passed | 143 failed | 27 failed as expected
 
 

tests/SelfTest/Baselines/compact.sw.multi.approved.txt

@@ -570,6 +570,10 @@ Matchers.tests.cpp:<line number>: failed: throwsSpecialException( 3 ), SpecialEx
 Matchers.tests.cpp:<line number>: failed: throwsSpecialException( 4 ), SpecialException, ExceptionMatcher{ 1 } for: SpecialException::what special exception has value of 1
 Matchers.tests.cpp:<line number>: passed: throwsSpecialException( 1 ), SpecialException, ExceptionMatcher{ 1 } for: SpecialException::what special exception has value of 1
 Matchers.tests.cpp:<line number>: passed: throwsSpecialException( 2 ), SpecialException, ExceptionMatcher{ 2 } for: SpecialException::what special exception has value of 2
+Matchers.tests.cpp:<line number>: passed: throwsDerivedException(), DerivedException, MessageMatches( StartsWith( "Derived" ) ) for: DerivedException::what  matches "starts with: "Derived""
+Matchers.tests.cpp:<line number>: passed: throwsDerivedException(), DerivedException, MessageMatches( EndsWith( "::what" ) ) for: DerivedException::what  matches "ends with: "::what""
+Matchers.tests.cpp:<line number>: passed: throwsDerivedException(), DerivedException, MessageMatches( !StartsWith( "::what" ) ) for: DerivedException::what  matches "not starts with: "::what""
+Matchers.tests.cpp:<line number>: passed: throwsSpecialException( 2 ), SpecialException, MessageMatches( StartsWith( "Special" ) ) for: SpecialException::what  matches "starts with: "Special""
 Exception.tests.cpp:<line number>: passed: thisThrows(), "expected exception" for: "expected exception" equals: "expected exception"
 Exception.tests.cpp:<line number>: passed: thisThrows(), Equals( "expecteD Exception", Catch::CaseSensitive::No ) for: "expected exception" equals: "expected exception" (case insensitive)
 Exception.tests.cpp:<line number>: passed: thisThrows(), StartsWith( "expected" ) for: "expected exception" starts with: "expected"
@@ -2451,7 +2455,7 @@ InternalBenchmark.tests.cpp:<line number>: passed: med == 18. for: 18.0 == 18.0
 InternalBenchmark.tests.cpp:<line number>: passed: q3 == 23. for: 23.0 == 23.0
 Misc.tests.cpp:<line number>: passed:
 Misc.tests.cpp:<line number>: passed:
-test cases:  394 |  304 passed |  83 failed |  7 failed as expected
-assertions: 2159 | 1989 passed | 143 failed | 27 failed as expected
+test cases:  395 |  305 passed |  83 failed |  7 failed as expected
+assertions: 2163 | 1993 passed | 143 failed | 27 failed as expected
 
 

tests/SelfTest/Baselines/console.std.approved.txt

@@ -1394,6 +1394,6 @@ due to unexpected exception with message:
   Why would you throw a std::string?
 
 ===============================================================================
-test cases:  394 |  318 passed |  69 failed |  7 failed as expected
-assertions: 2144 | 1989 passed | 128 failed | 27 failed as expected
+test cases:  395 |  319 passed |  69 failed |  7 failed as expected
+assertions: 2148 | 1993 passed | 128 failed | 27 failed as expected
 

tests/SelfTest/Baselines/console.sw.approved.txt

@@ -4282,6 +4282,32 @@ Matchers.tests.cpp:<line number>: PASSED:
 with expansion:
   SpecialException::what special exception has value of 2
 
+-------------------------------------------------------------------------------
+Exception message can be matched
+-------------------------------------------------------------------------------
+Matchers.tests.cpp:<line number>
+...............................................................................
+
+Matchers.tests.cpp:<line number>: PASSED:
+  REQUIRE_THROWS_MATCHES( throwsDerivedException(), DerivedException, MessageMatches( StartsWith( "Derived" ) ) )
+with expansion:
+  DerivedException::what  matches "starts with: "Derived""
+
+Matchers.tests.cpp:<line number>: PASSED:
+  REQUIRE_THROWS_MATCHES( throwsDerivedException(), DerivedException, MessageMatches( EndsWith( "::what" ) ) )
+with expansion:
+  DerivedException::what  matches "ends with: "::what""
+
+Matchers.tests.cpp:<line number>: PASSED:
+  REQUIRE_THROWS_MATCHES( throwsDerivedException(), DerivedException, MessageMatches( !StartsWith( "::what" ) ) )
+with expansion:
+  DerivedException::what  matches "not starts with: "::what""
+
+Matchers.tests.cpp:<line number>: PASSED:
+  REQUIRE_THROWS_MATCHES( throwsSpecialException( 2 ), SpecialException, MessageMatches( StartsWith( "Special" ) ) )
+with expansion:
+  SpecialException::what  matches "starts with: "Special""
+
 -------------------------------------------------------------------------------
 Exception messages can be tested for
   exact match
@@ -17518,6 +17544,6 @@ Misc.tests.cpp:<line number>
 Misc.tests.cpp:<line number>: PASSED:
 
 ===============================================================================
-test cases:  394 |  304 passed |  83 failed |  7 failed as expected
-assertions: 2159 | 1989 passed | 143 failed | 27 failed as expected
+test cases:  395 |  305 passed |  83 failed |  7 failed as expected
+assertions: 2163 | 1993 passed | 143 failed | 27 failed as expected
 

tests/SelfTest/Baselines/console.sw.multi.approved.txt

@@ -4280,6 +4280,32 @@ Matchers.tests.cpp:<line number>: PASSED:
 with expansion:
   SpecialException::what special exception has value of 2
 
+-------------------------------------------------------------------------------
+Exception message can be matched
+-------------------------------------------------------------------------------
+Matchers.tests.cpp:<line number>
+...............................................................................
+
+Matchers.tests.cpp:<line number>: PASSED:
+  REQUIRE_THROWS_MATCHES( throwsDerivedException(), DerivedException, MessageMatches( StartsWith( "Derived" ) ) )
+with expansion:
+  DerivedException::what  matches "starts with: "Derived""
+
+Matchers.tests.cpp:<line number>: PASSED:
+  REQUIRE_THROWS_MATCHES( throwsDerivedException(), DerivedException, MessageMatches( EndsWith( "::what" ) ) )
+with expansion:
+  DerivedException::what  matches "ends with: "::what""
+
+Matchers.tests.cpp:<line number>: PASSED:
+  REQUIRE_THROWS_MATCHES( throwsDerivedException(), DerivedException, MessageMatches( !StartsWith( "::what" ) ) )
+with expansion:
+  DerivedException::what  matches "not starts with: "::what""
+
+Matchers.tests.cpp:<line number>: PASSED:
+  REQUIRE_THROWS_MATCHES( throwsSpecialException( 2 ), SpecialException, MessageMatches( StartsWith( "Special" ) ) )
+with expansion:
+  SpecialException::what  matches "starts with: "Special""
+
 -------------------------------------------------------------------------------
 Exception messages can be tested for
   exact match
@@ -17510,6 +17536,6 @@ Misc.tests.cpp:<line number>
 Misc.tests.cpp:<line number>: PASSED:
 
 ===============================================================================
-test cases:  394 |  304 passed |  83 failed |  7 failed as expected
-assertions: 2159 | 1989 passed | 143 failed | 27 failed as expected
+test cases:  395 |  305 passed |  83 failed |  7 failed as expected
+assertions: 2163 | 1993 passed | 143 failed | 27 failed as expected
 

tests/SelfTest/Baselines/junit.sw.approved.txt

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <testsuitesloose text artifact
 >
-  <testsuite name="<exe-name>" errors="17" failures="126" tests="2159" hostname="tbd" time="{duration}" timestamp="{iso8601-timestamp}">
+  <testsuite name="<exe-name>" errors="17" failures="126" tests="2163" hostname="tbd" time="{duration}" timestamp="{iso8601-timestamp}">
     <properties>
       <property name="random-seed" value="1"/>
       <property name="filters" value="&quot;*&quot; ~[!nonportable] ~[!benchmark] ~[approvals]"/>
@@ -634,6 +634,7 @@ Matchers.tests.cpp:<line number>
       </failure>
     </testcase>
     <testcase classname="<exe-name>.global" name="Exception matchers that succeed" time="{duration}" status="run"/>
+    <testcase classname="<exe-name>.global" name="Exception message can be matched" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Exception messages can be tested for/exact match" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Exception messages can be tested for/different case" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Exception messages can be tested for/wildcarded" time="{duration}" status="run"/>

tests/SelfTest/Baselines/junit.sw.multi.approved.txt

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <testsuites>
-  <testsuite name="<exe-name>" errors="17" failures="126" tests="2159" hostname="tbd" time="{duration}" timestamp="{iso8601-timestamp}">
+  <testsuite name="<exe-name>" errors="17" failures="126" tests="2163" hostname="tbd" time="{duration}" timestamp="{iso8601-timestamp}">
     <properties>
       <property name="random-seed" value="1"/>
       <property name="filters" value="&quot;*&quot; ~[!nonportable] ~[!benchmark] ~[approvals]"/>
@@ -633,6 +633,7 @@ Matchers.tests.cpp:<line number>
       </failure>
     </testcase>
     <testcase classname="<exe-name>.global" name="Exception matchers that succeed" time="{duration}" status="run"/>
+    <testcase classname="<exe-name>.global" name="Exception message can be matched" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Exception messages can be tested for/exact match" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Exception messages can be tested for/different case" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Exception messages can be tested for/wildcarded" time="{duration}" status="run"/>

tests/SelfTest/Baselines/sonarqube.sw.approved.txt

@@ -1156,6 +1156,7 @@ Matchers.tests.cpp:<line number>
       </failure>
     </testCase>
     <testCase name="Exception matchers that succeed" duration="{duration}"/>
+    <testCase name="Exception message can be matched" duration="{duration}"/>
     <testCase name="Exceptions matchers" duration="{duration}"/>
     <testCase name="Floating point matchers: double/Relative" duration="{duration}"/>
     <testCase name="Floating point matchers: double/Relative/Some subnormal values" duration="{duration}"/>

tests/SelfTest/Baselines/sonarqube.sw.multi.approved.txt

@@ -1155,6 +1155,7 @@ Matchers.tests.cpp:<line number>
       </failure>
     </testCase>
     <testCase name="Exception matchers that succeed" duration="{duration}"/>
+    <testCase name="Exception message can be matched" duration="{duration}"/>
     <testCase name="Exceptions matchers" duration="{duration}"/>
     <testCase name="Floating point matchers: double/Relative" duration="{duration}"/>
     <testCase name="Floating point matchers: double/Relative/Some subnormal values" duration="{duration}"/>

tests/SelfTest/Baselines/tap.sw.approved.txt

@@ -1076,6 +1076,14 @@ not ok {test-number} - throwsSpecialException( 4 ), SpecialException, ExceptionM
 ok {test-number} - throwsSpecialException( 1 ), SpecialException, ExceptionMatcher{ 1 } for: SpecialException::what special exception has value of 1
 # Exception matchers that succeed
 ok {test-number} - throwsSpecialException( 2 ), SpecialException, ExceptionMatcher{ 2 } for: SpecialException::what special exception has value of 2
+# Exception message can be matched
+ok {test-number} - throwsDerivedException(), DerivedException, MessageMatches( StartsWith( "Derived" ) ) for: DerivedException::what  matches "starts with: "Derived""
+# Exception message can be matched
+ok {test-number} - throwsDerivedException(), DerivedException, MessageMatches( EndsWith( "::what" ) ) for: DerivedException::what  matches "ends with: "::what""
+# Exception message can be matched
+ok {test-number} - throwsDerivedException(), DerivedException, MessageMatches( !StartsWith( "::what" ) ) for: DerivedException::what  matches "not starts with: "::what""
+# Exception message can be matched
+ok {test-number} - throwsSpecialException( 2 ), SpecialException, MessageMatches( StartsWith( "Special" ) ) for: SpecialException::what  matches "starts with: "Special""
 # Exception messages can be tested for
 ok {test-number} - thisThrows(), "expected exception" for: "expected exception" equals: "expected exception"
 # Exception messages can be tested for
@@ -4322,5 +4330,5 @@ ok {test-number} - q3 == 23. for: 23.0 == 23.0
 ok {test-number} -
 # xmlentitycheck
 ok {test-number} -
-1..2159
+1..2163
 

tests/SelfTest/Baselines/tap.sw.multi.approved.txt

@@ -1074,6 +1074,14 @@ not ok {test-number} - throwsSpecialException( 4 ), SpecialException, ExceptionM
 ok {test-number} - throwsSpecialException( 1 ), SpecialException, ExceptionMatcher{ 1 } for: SpecialException::what special exception has value of 1
 # Exception matchers that succeed
 ok {test-number} - throwsSpecialException( 2 ), SpecialException, ExceptionMatcher{ 2 } for: SpecialException::what special exception has value of 2
+# Exception message can be matched
+ok {test-number} - throwsDerivedException(), DerivedException, MessageMatches( StartsWith( "Derived" ) ) for: DerivedException::what  matches "starts with: "Derived""
+# Exception message can be matched
+ok {test-number} - throwsDerivedException(), DerivedException, MessageMatches( EndsWith( "::what" ) ) for: DerivedException::what  matches "ends with: "::what""
+# Exception message can be matched
+ok {test-number} - throwsDerivedException(), DerivedException, MessageMatches( !StartsWith( "::what" ) ) for: DerivedException::what  matches "not starts with: "::what""
+# Exception message can be matched
+ok {test-number} - throwsSpecialException( 2 ), SpecialException, MessageMatches( StartsWith( "Special" ) ) for: SpecialException::what  matches "starts with: "Special""
 # Exception messages can be tested for
 ok {test-number} - thisThrows(), "expected exception" for: "expected exception" equals: "expected exception"
 # Exception messages can be tested for
@@ -4314,5 +4322,5 @@ ok {test-number} - q3 == 23. for: 23.0 == 23.0
 ok {test-number} -
 # xmlentitycheck
 ok {test-number} -
-1..2159
+1..2163
 

tests/SelfTest/Baselines/teamcity.sw.approved.txt

@@ -345,6 +345,8 @@ Matchers.tests.cpp:<line number>|nexpression failed|n  REQUIRE_THROWS_MATCHES( t
 ##teamcity[testFinished name='Exception matchers that fail' duration="{duration}"]
 ##teamcity[testStarted name='Exception matchers that succeed']
 ##teamcity[testFinished name='Exception matchers that succeed' duration="{duration}"]
+##teamcity[testStarted name='Exception message can be matched']
+##teamcity[testFinished name='Exception message can be matched' duration="{duration}"]
 ##teamcity[testStarted name='Exception messages can be tested for']
 ##teamcity[testFinished name='Exception messages can be tested for' duration="{duration}"]
 ##teamcity[testStarted name='Exceptions matchers']

tests/SelfTest/Baselines/teamcity.sw.multi.approved.txt

@@ -345,6 +345,8 @@ Matchers.tests.cpp:<line number>|nexpression failed|n  REQUIRE_THROWS_MATCHES( t
 ##teamcity[testFinished name='Exception matchers that fail' duration="{duration}"]
 ##teamcity[testStarted name='Exception matchers that succeed']
 ##teamcity[testFinished name='Exception matchers that succeed' duration="{duration}"]
+##teamcity[testStarted name='Exception message can be matched']
+##teamcity[testFinished name='Exception message can be matched' duration="{duration}"]
 ##teamcity[testStarted name='Exception messages can be tested for']
 ##teamcity[testFinished name='Exception messages can be tested for' duration="{duration}"]
 ##teamcity[testStarted name='Exceptions matchers']