Add tests for ColourGuard

tests/CMakeLists.txt

@@ -79,6 +79,7 @@ set(TEST_SOURCES
         ${SELF_TEST_DIR}/TestRegistrations.cpp
         ${SELF_TEST_DIR}/IntrospectiveTests/Clara.tests.cpp
         ${SELF_TEST_DIR}/IntrospectiveTests/CmdLine.tests.cpp
+        ${SELF_TEST_DIR}/IntrospectiveTests/ColourImpl.tests.cpp
         ${SELF_TEST_DIR}/IntrospectiveTests/Details.tests.cpp
         ${SELF_TEST_DIR}/IntrospectiveTests/FloatingPoint.tests.cpp
         ${SELF_TEST_DIR}/IntrospectiveTests/GeneratorsImpl.tests.cpp

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

@@ -104,6 +104,7 @@ Nor would this
 :test-result: PASS Character pretty printing
 :test-result: PASS Clara::Arg supports single-arg parse the way Opt does
 :test-result: PASS Clara::Opt supports accept-many lambdas
+:test-result: PASS ColourGuard behaviour
 :test-result: PASS Combining MatchAllOfGeneric does not nest
 :test-result: PASS Combining MatchAnyOfGeneric does not nest
 :test-result: PASS Combining MatchNotOfGeneric does not nest

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

@@ -102,6 +102,7 @@
 :test-result: PASS Character pretty printing
 :test-result: PASS Clara::Arg supports single-arg parse the way Opt does
 :test-result: PASS Clara::Opt supports accept-many lambdas
+:test-result: PASS ColourGuard behaviour
 :test-result: PASS Combining MatchAllOfGeneric does not nest
 :test-result: PASS Combining MatchAnyOfGeneric does not nest
 :test-result: PASS Combining MatchNotOfGeneric does not nest

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

@@ -366,6 +366,33 @@ Clara.tests.cpp:<line number>: passed: name == "foo" for: "foo" == "foo"
 Clara.tests.cpp:<line number>: passed: !(parse_result) for: !{?}
 Clara.tests.cpp:<line number>: passed: parse_result for: {?}
 Clara.tests.cpp:<line number>: passed: res == std::vector<std::string>{ "aaa", "bbb" } for: { "aaa", "bbb" } == { "aaa", "bbb" }
+ColourImpl.tests.cpp:<line number>: passed: streamWrapper.str().empty() for: true
+ColourImpl.tests.cpp:<line number>: passed: streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n" for: "1
+Using code: 2
+2
+Using code: 0
+3
+"
+==
+"1
+Using code: 2
+2
+Using code: 0
+3
+"
+ColourImpl.tests.cpp:<line number>: passed: streamWrapper.str() == "Using code: 2\nA\nB\nUsing code: 0\nC\n" for: "Using code: 2
+A
+B
+Using code: 0
+C
+"
+==
+"Using code: 2
+A
+B
+Using code: 0
+C
+"
 Matchers.tests.cpp:<line number>: passed: with 1 message: 'std::is_same< decltype( ( MatcherA() && MatcherB() ) && MatcherC() ), Catch::Matchers::Detail:: MatchAllOfGeneric<MatcherA, MatcherB, MatcherC>>::value'
 Matchers.tests.cpp:<line number>: passed: 1, ( MatcherA() && MatcherB() ) && MatcherC() for: 1 ( equals: (int) 1 or (float) 1.0f and equals: (long long) 1 and equals: (T) 1 )
 Matchers.tests.cpp:<line number>: passed: with 1 message: 'std::is_same< decltype( MatcherA() && ( MatcherB() && MatcherC() ) ), Catch::Matchers::Detail:: MatchAllOfGeneric<MatcherA, MatcherB, MatcherC>>::value'

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

@@ -364,6 +364,33 @@ Clara.tests.cpp:<line number>: passed: name == "foo" for: "foo" == "foo"
 Clara.tests.cpp:<line number>: passed: !(parse_result) for: !{?}
 Clara.tests.cpp:<line number>: passed: parse_result for: {?}
 Clara.tests.cpp:<line number>: passed: res == std::vector<std::string>{ "aaa", "bbb" } for: { "aaa", "bbb" } == { "aaa", "bbb" }
+ColourImpl.tests.cpp:<line number>: passed: streamWrapper.str().empty() for: true
+ColourImpl.tests.cpp:<line number>: passed: streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n" for: "1
+Using code: 2
+2
+Using code: 0
+3
+"
+==
+"1
+Using code: 2
+2
+Using code: 0
+3
+"
+ColourImpl.tests.cpp:<line number>: passed: streamWrapper.str() == "Using code: 2\nA\nB\nUsing code: 0\nC\n" for: "Using code: 2
+A
+B
+Using code: 0
+C
+"
+==
+"Using code: 2
+A
+B
+Using code: 0
+C
+"
 Matchers.tests.cpp:<line number>: passed: with 1 message: 'std::is_same< decltype( ( MatcherA() && MatcherB() ) && MatcherC() ), Catch::Matchers::Detail:: MatchAllOfGeneric<MatcherA, MatcherB, MatcherC>>::value'
 Matchers.tests.cpp:<line number>: passed: 1, ( MatcherA() && MatcherB() ) && MatcherC() for: 1 ( equals: (int) 1 or (float) 1.0f and equals: (long long) 1 and equals: (T) 1 )
 Matchers.tests.cpp:<line number>: passed: with 1 message: 'std::is_same< decltype( MatcherA() && ( MatcherB() && MatcherC() ) ), Catch::Matchers::Detail:: MatchAllOfGeneric<MatcherA, MatcherB, MatcherC>>::value'

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

@@ -1395,6 +1395,6 @@ due to unexpected exception with message:
   Why would you throw a std::string?
 
 ===============================================================================
-test cases:  385 |  309 passed |  69 failed |  7 failed as expected
-assertions: 2216 | 2061 passed | 128 failed | 27 failed as expected
+test cases:  386 |  310 passed |  69 failed |  7 failed as expected
+assertions: 2219 | 2064 passed | 128 failed | 27 failed as expected
 

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

@@ -3023,6 +3023,66 @@ Clara.tests.cpp:<line number>: PASSED:
 with expansion:
   { "aaa", "bbb" } == { "aaa", "bbb" }
 
+-------------------------------------------------------------------------------
+ColourGuard behaviour
+  ColourGuard is disengaged by default
+-------------------------------------------------------------------------------
+ColourImpl.tests.cpp:<line number>
+...............................................................................
+
+ColourImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( streamWrapper.str().empty() )
+with expansion:
+  true
+
+-------------------------------------------------------------------------------
+ColourGuard behaviour
+  ColourGuard is engaged by op<<
+-------------------------------------------------------------------------------
+ColourImpl.tests.cpp:<line number>
+...............................................................................
+
+ColourImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n" )
+with expansion:
+  "1
+  Using code: 2
+  2
+  Using code: 0
+  3
+  "
+  ==
+  "1
+  Using code: 2
+  2
+  Using code: 0
+  3
+  "
+
+-------------------------------------------------------------------------------
+ColourGuard behaviour
+  ColourGuard can be engaged explicitly
+-------------------------------------------------------------------------------
+ColourImpl.tests.cpp:<line number>
+...............................................................................
+
+ColourImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( streamWrapper.str() == "Using code: 2\nA\nB\nUsing code: 0\nC\n" )
+with expansion:
+  "Using code: 2
+  A
+  B
+  Using code: 0
+  C
+  "
+  ==
+  "Using code: 2
+  A
+  B
+  Using code: 0
+  C
+  "
+
 -------------------------------------------------------------------------------
 Combining MatchAllOfGeneric does not nest
 -------------------------------------------------------------------------------
@@ -17811,6 +17871,6 @@ Misc.tests.cpp:<line number>
 Misc.tests.cpp:<line number>: PASSED:
 
 ===============================================================================
-test cases:  385 |  295 passed |  83 failed |  7 failed as expected
-assertions: 2231 | 2061 passed | 143 failed | 27 failed as expected
+test cases:  386 |  296 passed |  83 failed |  7 failed as expected
+assertions: 2234 | 2064 passed | 143 failed | 27 failed as expected
 

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

@@ -3021,6 +3021,66 @@ Clara.tests.cpp:<line number>: PASSED:
 with expansion:
   { "aaa", "bbb" } == { "aaa", "bbb" }
 
+-------------------------------------------------------------------------------
+ColourGuard behaviour
+  ColourGuard is disengaged by default
+-------------------------------------------------------------------------------
+ColourImpl.tests.cpp:<line number>
+...............................................................................
+
+ColourImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( streamWrapper.str().empty() )
+with expansion:
+  true
+
+-------------------------------------------------------------------------------
+ColourGuard behaviour
+  ColourGuard is engaged by op<<
+-------------------------------------------------------------------------------
+ColourImpl.tests.cpp:<line number>
+...............................................................................
+
+ColourImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n" )
+with expansion:
+  "1
+  Using code: 2
+  2
+  Using code: 0
+  3
+  "
+  ==
+  "1
+  Using code: 2
+  2
+  Using code: 0
+  3
+  "
+
+-------------------------------------------------------------------------------
+ColourGuard behaviour
+  ColourGuard can be engaged explicitly
+-------------------------------------------------------------------------------
+ColourImpl.tests.cpp:<line number>
+...............................................................................
+
+ColourImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( streamWrapper.str() == "Using code: 2\nA\nB\nUsing code: 0\nC\n" )
+with expansion:
+  "Using code: 2
+  A
+  B
+  Using code: 0
+  C
+  "
+  ==
+  "Using code: 2
+  A
+  B
+  Using code: 0
+  C
+  "
+
 -------------------------------------------------------------------------------
 Combining MatchAllOfGeneric does not nest
 -------------------------------------------------------------------------------
@@ -17803,6 +17863,6 @@ Misc.tests.cpp:<line number>
 Misc.tests.cpp:<line number>: PASSED:
 
 ===============================================================================
-test cases:  385 |  295 passed |  83 failed |  7 failed as expected
-assertions: 2231 | 2061 passed | 143 failed | 27 failed as expected
+test cases:  386 |  296 passed |  83 failed |  7 failed as expected
+assertions: 2234 | 2064 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="2231" hostname="tbd" time="{duration}" timestamp="{iso8601-timestamp}">
+  <testsuite name="<exe-name>" errors="17" failures="126" tests="2234" hostname="tbd" time="{duration}" timestamp="{iso8601-timestamp}">
     <properties>
       <property name="random-seed" value="1"/>
       <property name="filters" value="~[!nonportable]~[!benchmark]~[approvals] *"/>
@@ -387,6 +387,9 @@ Exception.tests.cpp:<line number>
     <testcase classname="<exe-name>.global" name="Clara::Arg supports single-arg parse the way Opt does" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Clara::Opt supports accept-many lambdas/Parsing fails on multiple options without accept_many" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Clara::Opt supports accept-many lambdas/Parsing succeeds on multiple options with accept_many" time="{duration}" status="run"/>
+    <testcase classname="<exe-name>.global" name="ColourGuard behaviour/ColourGuard is disengaged by default" time="{duration}" status="run"/>
+    <testcase classname="<exe-name>.global" name="ColourGuard behaviour/ColourGuard is engaged by op&lt;&lt;" time="{duration}" status="run"/>
+    <testcase classname="<exe-name>.global" name="ColourGuard behaviour/ColourGuard can be engaged explicitly" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Combining MatchAllOfGeneric does not nest" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Combining MatchAnyOfGeneric does not nest" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Combining MatchNotOfGeneric does not nest" 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="2231" hostname="tbd" time="{duration}" timestamp="{iso8601-timestamp}">
+  <testsuite name="<exe-name>" errors="17" failures="126" tests="2234" hostname="tbd" time="{duration}" timestamp="{iso8601-timestamp}">
     <properties>
       <property name="random-seed" value="1"/>
       <property name="filters" value="~[!nonportable]~[!benchmark]~[approvals] *"/>
@@ -386,6 +386,9 @@ Exception.tests.cpp:<line number>
     <testcase classname="<exe-name>.global" name="Clara::Arg supports single-arg parse the way Opt does" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Clara::Opt supports accept-many lambdas/Parsing fails on multiple options without accept_many" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Clara::Opt supports accept-many lambdas/Parsing succeeds on multiple options with accept_many" time="{duration}" status="run"/>
+    <testcase classname="<exe-name>.global" name="ColourGuard behaviour/ColourGuard is disengaged by default" time="{duration}" status="run"/>
+    <testcase classname="<exe-name>.global" name="ColourGuard behaviour/ColourGuard is engaged by op&lt;&lt;" time="{duration}" status="run"/>
+    <testcase classname="<exe-name>.global" name="ColourGuard behaviour/ColourGuard can be engaged explicitly" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Combining MatchAllOfGeneric does not nest" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Combining MatchAnyOfGeneric does not nest" time="{duration}" status="run"/>
     <testcase classname="<exe-name>.global" name="Combining MatchNotOfGeneric does not nest" time="{duration}" status="run"/>

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

@@ -94,6 +94,11 @@
     <testCase name="Process can be configured on command line/Benchmark options/warmup-time" duration="{duration}"/>
     <testCase name="Test with special, characters &quot;in name" duration="{duration}"/>
   </file>
+  <file path="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp">
+    <testCase name="ColourGuard behaviour/ColourGuard is disengaged by default" duration="{duration}"/>
+    <testCase name="ColourGuard behaviour/ColourGuard is engaged by op&lt;&lt;" duration="{duration}"/>
+    <testCase name="ColourGuard behaviour/ColourGuard can be engaged explicitly" duration="{duration}"/>
+  </file>
   <file path="tests/<exe-name>/IntrospectiveTests/Details.tests.cpp">
     <testCase name="CaseInsensitiveEqualsTo is case insensitive/Degenerate cases" duration="{duration}"/>
     <testCase name="CaseInsensitiveEqualsTo is case insensitive/Plain comparisons" duration="{duration}"/>

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

@@ -93,6 +93,11 @@
     <testCase name="Process can be configured on command line/Benchmark options/warmup-time" duration="{duration}"/>
     <testCase name="Test with special, characters &quot;in name" duration="{duration}"/>
   </file>
+  <file path="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp">
+    <testCase name="ColourGuard behaviour/ColourGuard is disengaged by default" duration="{duration}"/>
+    <testCase name="ColourGuard behaviour/ColourGuard is engaged by op&lt;&lt;" duration="{duration}"/>
+    <testCase name="ColourGuard behaviour/ColourGuard can be engaged explicitly" duration="{duration}"/>
+  </file>
   <file path="tests/<exe-name>/IntrospectiveTests/Details.tests.cpp">
     <testCase name="CaseInsensitiveEqualsTo is case insensitive/Degenerate cases" duration="{duration}"/>
     <testCase name="CaseInsensitiveEqualsTo is case insensitive/Plain comparisons" duration="{duration}"/>

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

@@ -730,6 +730,12 @@ ok {test-number} - !(parse_result) for: !{?}
 ok {test-number} - parse_result for: {?}
 # Clara::Opt supports accept-many lambdas
 ok {test-number} - res == std::vector<std::string>{ "aaa", "bbb" } for: { "aaa", "bbb" } == { "aaa", "bbb" }
+# ColourGuard behaviour
+ok {test-number} - streamWrapper.str().empty() for: true
+# ColourGuard behaviour
+ok {test-number} - streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n" for: "1 Using code: 2 2 Using code: 0 3 " == "1 Using code: 2 2 Using code: 0 3 "
+# ColourGuard behaviour
+ok {test-number} - streamWrapper.str() == "Using code: 2\nA\nB\nUsing code: 0\nC\n" for: "Using code: 2 A B Using code: 0 C " == "Using code: 2 A B Using code: 0 C "
 # Combining MatchAllOfGeneric does not nest
 ok {test-number} - with 1 message: 'std::is_same< decltype( ( MatcherA() && MatcherB() ) && MatcherC() ), Catch::Matchers::Detail:: MatchAllOfGeneric<MatcherA, MatcherB, MatcherC>>::value'
 # Combining MatchAllOfGeneric does not nest
@@ -4464,5 +4470,5 @@ ok {test-number} - q3 == 23. for: 23.0 == 23.0
 ok {test-number} -
 # xmlentitycheck
 ok {test-number} -
-1..2231
+1..2234
 

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

@@ -728,6 +728,12 @@ ok {test-number} - !(parse_result) for: !{?}
 ok {test-number} - parse_result for: {?}
 # Clara::Opt supports accept-many lambdas
 ok {test-number} - res == std::vector<std::string>{ "aaa", "bbb" } for: { "aaa", "bbb" } == { "aaa", "bbb" }
+# ColourGuard behaviour
+ok {test-number} - streamWrapper.str().empty() for: true
+# ColourGuard behaviour
+ok {test-number} - streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n" for: "1 Using code: 2 2 Using code: 0 3 " == "1 Using code: 2 2 Using code: 0 3 "
+# ColourGuard behaviour
+ok {test-number} - streamWrapper.str() == "Using code: 2\nA\nB\nUsing code: 0\nC\n" for: "Using code: 2 A B Using code: 0 C " == "Using code: 2 A B Using code: 0 C "
 # Combining MatchAllOfGeneric does not nest
 ok {test-number} - with 1 message: 'std::is_same< decltype( ( MatcherA() && MatcherB() ) && MatcherC() ), Catch::Matchers::Detail:: MatchAllOfGeneric<MatcherA, MatcherB, MatcherC>>::value'
 # Combining MatchAllOfGeneric does not nest
@@ -4456,5 +4462,5 @@ ok {test-number} - q3 == 23. for: 23.0 == 23.0
 ok {test-number} -
 # xmlentitycheck
 ok {test-number} -
-1..2231
+1..2234
 

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

@@ -241,6 +241,8 @@ Exception.tests.cpp:<line number>|nunexpected exception with message:|n  "unexpe
 ##teamcity[testFinished name='Clara::Arg supports single-arg parse the way Opt does' duration="{duration}"]
 ##teamcity[testStarted name='Clara::Opt supports accept-many lambdas']
 ##teamcity[testFinished name='Clara::Opt supports accept-many lambdas' duration="{duration}"]
+##teamcity[testStarted name='ColourGuard behaviour']
+##teamcity[testFinished name='ColourGuard behaviour' duration="{duration}"]
 ##teamcity[testStarted name='Combining MatchAllOfGeneric does not nest']
 ##teamcity[testFinished name='Combining MatchAllOfGeneric does not nest' duration="{duration}"]
 ##teamcity[testStarted name='Combining MatchAnyOfGeneric does not nest']

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

@@ -241,6 +241,8 @@ Exception.tests.cpp:<line number>|nunexpected exception with message:|n  "unexpe
 ##teamcity[testFinished name='Clara::Arg supports single-arg parse the way Opt does' duration="{duration}"]
 ##teamcity[testStarted name='Clara::Opt supports accept-many lambdas']
 ##teamcity[testFinished name='Clara::Opt supports accept-many lambdas' duration="{duration}"]
+##teamcity[testStarted name='ColourGuard behaviour']
+##teamcity[testFinished name='ColourGuard behaviour' duration="{duration}"]
 ##teamcity[testStarted name='Combining MatchAllOfGeneric does not nest']
 ##teamcity[testFinished name='Combining MatchAllOfGeneric does not nest' duration="{duration}"]
 ##teamcity[testStarted name='Combining MatchAnyOfGeneric does not nest']

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

@@ -3308,6 +3308,66 @@ Nor would this
     </Section>
     <OverallResult success="true"/>
   </TestCase>
+  <TestCase name="ColourGuard behaviour" tags="[console-colours]" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+    <Section name="ColourGuard is disengaged by default" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+      <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+        <Original>
+          streamWrapper.str().empty()
+        </Original>
+        <Expanded>
+          true
+        </Expanded>
+      </Expression>
+      <OverallResults successes="1" failures="0" expectedFailures="0"/>
+    </Section>
+    <Section name="ColourGuard is engaged by op&lt;&lt;" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+      <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+        <Original>
+          streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n"
+        </Original>
+        <Expanded>
+          "1
+Using code: 2
+2
+Using code: 0
+3
+"
+==
+"1
+Using code: 2
+2
+Using code: 0
+3
+"
+        </Expanded>
+      </Expression>
+      <OverallResults successes="1" failures="0" expectedFailures="0"/>
+    </Section>
+    <Section name="ColourGuard can be engaged explicitly" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+      <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+        <Original>
+          streamWrapper.str() == "Using code: 2\nA\nB\nUsing code: 0\nC\n"
+        </Original>
+        <Expanded>
+          "Using code: 2
+A
+B
+Using code: 0
+C
+"
+==
+"Using code: 2
+A
+B
+Using code: 0
+C
+"
+        </Expanded>
+      </Expression>
+      <OverallResults successes="1" failures="0" expectedFailures="0"/>
+    </Section>
+    <OverallResult success="true"/>
+  </TestCase>
   <TestCase name="Combining MatchAllOfGeneric does not nest" tags="[matchers][templated]" filename="tests/<exe-name>/UsageTests/Matchers.tests.cpp" >
     <Expression success="true" type="REQUIRE_THAT" filename="tests/<exe-name>/UsageTests/Matchers.tests.cpp" >
       <Original>
@@ -20931,6 +20991,6 @@ loose text artifact
     </Section>
     <OverallResult success="true"/>
   </TestCase>
-  <OverallResults successes="2061" failures="143" expectedFailures="27"/>
-  <OverallResultsCases successes="295" failures="83" expectedFailures="7"/>
+  <OverallResults successes="2064" failures="143" expectedFailures="27"/>
+  <OverallResultsCases successes="296" failures="83" expectedFailures="7"/>
 </Catch2TestRun>

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

@@ -3308,6 +3308,66 @@ Nor would this
     </Section>
     <OverallResult success="true"/>
   </TestCase>
+  <TestCase name="ColourGuard behaviour" tags="[console-colours]" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+    <Section name="ColourGuard is disengaged by default" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+      <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+        <Original>
+          streamWrapper.str().empty()
+        </Original>
+        <Expanded>
+          true
+        </Expanded>
+      </Expression>
+      <OverallResults successes="1" failures="0" expectedFailures="0"/>
+    </Section>
+    <Section name="ColourGuard is engaged by op&lt;&lt;" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+      <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+        <Original>
+          streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n"
+        </Original>
+        <Expanded>
+          "1
+Using code: 2
+2
+Using code: 0
+3
+"
+==
+"1
+Using code: 2
+2
+Using code: 0
+3
+"
+        </Expanded>
+      </Expression>
+      <OverallResults successes="1" failures="0" expectedFailures="0"/>
+    </Section>
+    <Section name="ColourGuard can be engaged explicitly" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+      <Expression success="true" type="REQUIRE" filename="tests/<exe-name>/IntrospectiveTests/ColourImpl.tests.cpp" >
+        <Original>
+          streamWrapper.str() == "Using code: 2\nA\nB\nUsing code: 0\nC\n"
+        </Original>
+        <Expanded>
+          "Using code: 2
+A
+B
+Using code: 0
+C
+"
+==
+"Using code: 2
+A
+B
+Using code: 0
+C
+"
+        </Expanded>
+      </Expression>
+      <OverallResults successes="1" failures="0" expectedFailures="0"/>
+    </Section>
+    <OverallResult success="true"/>
+  </TestCase>
   <TestCase name="Combining MatchAllOfGeneric does not nest" tags="[matchers][templated]" filename="tests/<exe-name>/UsageTests/Matchers.tests.cpp" >
     <Expression success="true" type="REQUIRE_THAT" filename="tests/<exe-name>/UsageTests/Matchers.tests.cpp" >
       <Original>
@@ -20930,6 +20990,6 @@ There is no extra whitespace here
     </Section>
     <OverallResult success="true"/>
   </TestCase>
-  <OverallResults successes="2061" failures="143" expectedFailures="27"/>
-  <OverallResultsCases successes="295" failures="83" expectedFailures="7"/>
+  <OverallResults successes="2064" failures="143" expectedFailures="27"/>
+  <OverallResultsCases successes="296" failures="83" expectedFailures="7"/>
 </Catch2TestRun>

tests/SelfTest/IntrospectiveTests/ColourImpl.tests.cpp

@@ -0,0 +1,63 @@
+
+//              Copyright Catch2 Authors
+// Distributed under the Boost Software License, Version 1.0.
+//   (See accompanying file LICENSE_1_0.txt or copy at
+//        https://www.boost.org/LICENSE_1_0.txt)
+
+// SPDX-License-Identifier: BSL-1.0
+
+#include <catch2/catch_test_macros.hpp>
+#include <catch2/internal/catch_console_colour.hpp>
+
+#include <sstream>
+
+namespace {
+    class TestColourImpl : public Catch::ColourImpl {
+        using Catch::ColourImpl::ColourImpl;
+        // Inherited via ColourImpl
+        void use( Catch::Colour::Code colourCode ) const override {
+            m_stream->stream() << "Using code: " << colourCode << '\n';
+        }
+    };
+
+    class TestStringStream : public Catch::IStream {
+        mutable std::stringstream m_stream;
+    public:
+        std::ostream& stream() const override {
+            return m_stream;
+        }
+
+        std::string str() const { return m_stream.str(); }
+    };
+}
+
+TEST_CASE("ColourGuard behaviour", "[console-colours]") {
+    TestStringStream streamWrapper;
+    TestColourImpl colourImpl( &streamWrapper );
+    auto& stream = streamWrapper.stream();
+
+    SECTION("ColourGuard is disengaged by default") {
+        { auto guard = colourImpl.guardColour( Catch::Colour::Red ); }
+
+        REQUIRE( streamWrapper.str().empty() );
+    }
+
+    SECTION("ColourGuard is engaged by op<<") {
+        stream << "1\n" << colourImpl.guardColour( Catch::Colour::Red ) << "2\n";
+        stream << "3\n";
+
+        REQUIRE( streamWrapper.str() == "1\nUsing code: 2\n2\nUsing code: 0\n3\n" );
+    }
+
+    SECTION("ColourGuard can be engaged explicitly") {
+        {
+            auto guard =
+                colourImpl.guardColour( Catch::Colour::Red ).engage( stream );
+            stream << "A\n"
+                   << "B\n";
+        }
+        stream << "C\n";
+        REQUIRE( streamWrapper.str() ==
+                 "Using code: 2\nA\nB\nUsing code: 0\nC\n" );
+    }
+}