Various updates to the documentation

JohnnyHendriks · Mar 13, 2021 · d912920 · d912920
1 parent 7c4cb21
commit d912920
Show file tree

Hide file tree

Showing 6 changed files with 41 additions and 17 deletions.
diff --git a/Docs/Build.md b/Docs/Build.md
@@ -16,7 +16,7 @@ For those that want to add the test adapter to their own extension repository, b
  <title type="text">Test Adapter for Catch2.</title>
  <summary type="text">Visual Studio Test Adaptor for use with Catch2 test framework.</summary>
  <published>2018-06-24T12:17:00Z</published>
- <updated>2018-08-18T08:17:00Z</updated>
+ <updated>2021-03-09T08:17:00Z</updated>
  <author>
  <name>Johnny Hendriks</name>
  </author>
@@ -25,11 +25,11 @@ For those that want to add the test adapter to their own extension repository, b
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://schemas.microsoft.com/developer/vsx-syndication-schema/2010"> 
  <Id>VSTestAdapterCatch2.73ba8471-3771-47bf-bd23-49a1ba09af89</Id>
- <Version>1.3.0</Version>
+ <Version>1.6.0</Version>
  <References />
  <Rating xsi:nil="true" />
  <RatingCount xsi:nil="true" />
  <DownloadCount xsi:nil="true" />
  </Vsix>
  </entry>
-```
+```
diff --git a/Docs/Capabilities.md b/Docs/Capabilities.md
@@ -39,14 +39,14 @@ During test case name discovery trailing spaces are automatically removed from a
 
 ### Long test case names
 
-When default test discovery is used (_i.e._, using the "--list-tests" or "-l" Catch2 discovery option), long test case names are split over multiple lines during discovery when they contain more than 77 characters. In the resulting split some information may be lost. Typically, a split may occur at the location of a space character. Should that location be a sequence of multiple space characters then information about the additional space characters is lost. The result is that though the test will show up in the Test Explorer, it cannot be run from the Test Explorer.
+When default test discovery is used (_i.e._, using the "--list-tests" or "-l" Catch2 discovery option), long test case names are typically split over multiple lines during discovery when they contain more than 77 characters. In the resulting split some information may be lost. Typically, a split may occur at the location of a space character. Should that location be a sequence of multiple space characters then information about the additional space characters is lost. The result is that though the test will show up in the Test Explorer, it cannot be run from the Test Explorer.
 
 Very long character sequences without spaces may get split as well in which case a dash '-' is added to indicate the split. There are corner cases where a dash is part of the name but may be interpreted as a split character. This would again result in in an inability to run the test from the Test Explorer.
 
 Basically, it is assumed that the split of the line requires a single space to be added to the name at that point. Note, this also is assumed if the split occurs at the '.' character. Similar restrictions apply to the Tag names.
 
-Note, when a [customized discovery mechanism](Settings.md#discovercommandline) is used, these problems do not occur.
+In version 1.6.0 of the **Test Adapter for Catch2** improvements were made in this area, but there are still corner cases that cannot be handled correctly. Note, when a [customized discovery mechanism](Settings.md#discovercommandline) is used, these problems do not occur.
 
 ### Catch2 specific
 
-Test case names are semi case sensitive. Test cases which only differ in case are separate test cases as far as Catch2 is concerned. However, they cannot be called individually via the command line. As such, when such a test is called, all tests with the same case insensitive name are run. As of version 1.3 of the **Test Adapter for Catch2** this situation is handled more gracefully and at least the correct test results is shown for the test case. The assertion statistics shown for the test case are those of all the run tests, including the ones with only differ in case. As a result, it is possible that a passed test case contains failed assertions in the shown assertion statistics. For clarity a note is added to the test case result message to indicate this. Before version 1.3 of the **Test Adapter for Catch2** this corner case was not handled well and therefore could report the wrong result for those test cases.
+Test case names are semi case sensitive. Test cases which only differ in case are separate test cases as far as Catch2 is concerned. However, they cannot be called individually via the command line. As such, when such a test is called, all tests with the same case insensitive name are run. As of version 1.3.0 of the **Test Adapter for Catch2** this situation is handled more gracefully and at least the correct test results is shown for the test case. The assertion statistics shown for the test case are those of all the run tests, including the ones with only differ in case. As a result, it is possible that a passed test case contains failed assertions in the shown assertion statistics. For clarity a note is added to the test case result message to indicate this. Before version 1.3.0 of the **Test Adapter for Catch2** this corner case was not handled well and therefore could report the wrong result for those test cases.
diff --git a/Docs/Readme.md b/Docs/Readme.md
@@ -18,14 +18,19 @@ The following is an example _.runsettings_ file that contains options specific f
 
  <!-- Adapter Specific sections -->
  <Catch2Adapter>
+ <CombinedTimeout>60000</CombinedTimeout><!-- Milliseconds; Introduced in v1.6.0 -->
  <DebugBreak>on</DebugBreak><!-- Introduced in v1.1.0 -->
- <DiscoverCommandLine>--list-tests *</DiscoverCommandLine>
+ <DiscoverCommandLine>--verbosity high --list-tests *</DiscoverCommandLine>
  <DiscoverTimeout>500</DiscoverTimeout><!-- Milliseconds -->
+ <ExecutionMode>Combined</ExecutionMode><!-- Introduced in v1.6.0 -->
+ <ExecutionModeForceSingleTagRgx>Slow</ExecutionModeForceSingleTagRgx><!-- Introduced in v1.6.0 -->
  <FilenameFilter>^Catch_</FilenameFilter><!-- Regex filter -->
  <IncludeHidden>true</IncludeHidden>
  <Logging>normal</Logging>
  <MessageFormat>StatsOnly</MessageFormat>
  <StackTraceFormat>ShortInfo</StackTraceFormat>
+ <StackTraceMaxLength>60</StackTraceMaxLength><!-- Introduced in v1.6.0 -->
+ <StackTracePointReplacement>,</StackTracePointReplacement><!-- Introduced in v1.3.0 -->
  <TestCaseTimeout>20000</TestCaseTimeout><!-- Milliseconds -->
  <WorkingDirectory>..\TestData</WorkingDirectory>
  <WorkingDirectoryRoot>Executable</WorkingDirectoryRoot>
@@ -34,12 +39,27 @@ The following is an example _.runsettings_ file that contains options specific f
 </RunSettings>
  ```
 
+Not all settings need to be provided though, the following is an example of a minimalistic _.runsettings_ file.
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<RunSettings>
+
+ <!-- Adapter Specific sections -->
+ <Catch2Adapter>
+ <FilenameFilter>.*</FilenameFilter><!-- Regex filter -->
+ </Catch2Adapter>
+
+</RunSettings>
+ ```
+
 # Details
 
 For a more detailed description see the following pages:
 
 - [Capabilities](Capabilities.md)
-- [Walkthrough: using the Test Adapter for Catch2](Walkthrough.md)
+- [Walkthrough VS2019: using the Test Adapter for Catch2](Walkthrough-vs2019.md)
+- [Walkthrough VS2017: using the Test Adapter for Catch2](Walkthrough-vs2017.md)
 - [Settings](Settings.md)
 - [Testcase Discovery](Discovery.md)
 - [How to build the test adapter](Build.md)

diff --git a/Docs/Settings.md b/Docs/Settings.md
@@ -1,8 +1,8 @@
 # Settings for Test Adapter for Catch2
 
-> The information on this page is based on **Test Adapter for Catch2** v1.5.0.
+> The information on this page is based on **Test Adapter for Catch2** v1.6.0.
 
-In order for the **Test Adapter for Catch2** to do its job, it requires certain settings to be set explicitely by the user. This is done via a _.runsettings_ file. The settings for the **Test Adapter for Catch2** are collected inside the `<Catch2Adapter>` node that can be added to the `<RunSettings>` node of the _.runsettings_ file. Below is the list of settings that are available for the **Test Adapter for Catch2**. The ones with an asterisk are required to be set by the user and have defaults that will cause the **Test Adapter for Catch2** to not discovery tests.
+In order for the **Test Adapter for Catch2** to do its job, it requires certain settings to be set explicitly by the user. This is done via a _.runsettings_ file. The settings for the **Test Adapter for Catch2** are collected inside the `<Catch2Adapter>` node that can be added to the `<RunSettings>` node of the _.runsettings_ file. Below is the list of settings that are available for the **Test Adapter for Catch2**. The ones with an asterisk are required to be set by the user and have defaults that will cause the **Test Adapter for Catch2** to not discovery tests.
 
 - [`<Catch2Adapter>`](#catch2adapter)
 - [`<CombinedTimeout>`](#combinedtimeout)
@@ -32,15 +32,19 @@ The following _.runsettings_ file examples only contains settings specific to th
 
  <!-- Adapter Specific sections -->
  <Catch2Adapter>
- <DebugBreak>on</DebugBreak><!-- Introduced in v1.1.0 -->
+ <CombinedTimeout>60000</CombinedTimeout><!-- Milliseconds; Introduced in v1.6.0 -->
+ <DebugBreak>on</DebugBreak>
  <DiscoverCommandLine>--verbosity high --list-tests *</DiscoverCommandLine>
  <DiscoverTimeout>500</DiscoverTimeout><!-- Milliseconds -->
+ <ExecutionMode>Combined</ExecutionMode><!-- Introduced in v1.6.0 -->
+ <ExecutionModeForceSingleTagRgx>Slow</ExecutionModeForceSingleTagRgx><!-- Introduced in v1.6.0 -->
  <FilenameFilter>^Catch_</FilenameFilter><!-- Regex filter -->
  <IncludeHidden>true</IncludeHidden>
  <Logging>normal</Logging>
  <MessageFormat>StatsOnly</MessageFormat>
  <StackTraceFormat>ShortInfo</StackTraceFormat>
- <StackTracePointReplacement>,</StackTracePointReplacement><!-- Introduced in v1.3.0 -->
+ <StackTraceMaxLength>60</StackTraceMaxLength><!-- Introduced in v1.6.0 -->
+ <StackTracePointReplacement>,</StackTracePointReplacement>
  <TestCaseTimeout>20000</TestCaseTimeout><!-- Milliseconds -->
  <WorkingDirectory>..\TestData</WorkingDirectory>
  <WorkingDirectoryRoot>Executable</WorkingDirectoryRoot>

diff --git a/README.md b/README.md
@@ -16,10 +16,10 @@ For documentation on the **Test Adapter for Catch2** see the followng links.
 
 - [Overview](Docs/Readme.md)
 - [Capabilities](Docs/Capabilities.md)
-- [Walkthrough VS2019: using the Test Adapter for Catch2](Docs/Walkthrough-2019.md)
-- [Walkthrough VS2017: using the Test Adapter for Catch2](Docs/Walkthrough-2017.md)
+- [Walkthrough VS2019: using the Test Adapter for Catch2](Docs/Walkthrough-vs2019.md)
+- [Walkthrough VS2017: using the Test Adapter for Catch2](Docs/Walkthrough-vs2017.md)
 - [Settings](Docs/Settings.md)
 - [Testcase Discovery](Docs/Discovery.md)
 - [How to build the test adapter](Docs/Build.md)
 - [Known issues](Docs/Known-issues.md)
-- [Change log](Docs/CHANGELOG.md)
+- [Change log](Docs/CHANGELOG.md)
diff --git a/ReferenceTests/walkthrough/Readme.md b/ReferenceTests/walkthrough/Readme.md
@@ -2,6 +2,6 @@
 
 For the development of the **Test Adapter for Catch2** some Catch2 tests were created. Some of these tests are actually used in the unit tests for the different components of the **Test Adapter for Catch2**. Others are just used the manually check how the test adapter handles them. So expect many of the tests to be failing tests.
 
-The solutions you find here is added specifically for use with the [walkthrough](../../Docs/Walkthrough.md). Note two solutions are provided, one for use with Visual Studio 2017 and one for use with Visual Studio 2019. The name of the solution should give you a hint which solution is meant for which Visual Studio Version. Note that the walkthrough was made with Visual Studio 2017. In Visual Studio 2019 the Test Explorer has undergone a facelift and things work slightly different.
+The solutions you find here were added specifically for use with the [walkthrough VS2017](../../Docs/Walkthrough-vs2017.md) and [walkthrough VS2019](../../Docs/Walkthrough-vs2019.md). Note two solutions are provided, one for use with Visual Studio 2017 and one for use with Visual Studio 2019. The name of the solution should give you a hint which solution is meant for which Visual Studio Version.
 
-**Warning: the written tests do not necessarily follow best practices.**
+**Warning: the written tests do not necessarily follow best practices.**