Docs for Visual Studio integration

docs/reference-index.md

@@ -8,6 +8,7 @@ Before looking at this material be sure to read the [tutorial](tutorial.md)
 * [Logging Macros](logging.md)
 * [Supplying your own main()](own-main.md)
 * [Test fixtures](test-fixtures.md)
+* [Visual Studio integration](vs/vs-index.md)
 
 ---
 

docs/vs/VS2010instructions.md

@@ -0,0 +1,59 @@
+Creating managed tests in VS2010 is pretty easy, but requires a small amount of extra work to be able to use Catch.
+
+[pre-requisite - obviously, you'll also need Catch - my copy is in C:\Projects\Phil\Catch in the following examples...and I'm using the normal, multiple include files.]
+
+## First, start by creating a new project
+
+Choose 'File' ==> 'New' ==> 'Project' and select a new Visual C++ Test project:
+![VS2010 test project](VS2010testproject.png)
+
+Now we need to change some build options, so right click the project and choose 'Properties':
+
+First, in the 'General' options, change 'Common Language Runtime Support' to use basic clr:
+
+![VS2010 clr options](VS2010options-clr.png)
+
+By default, Unicode will have been enabled - it is up to you whether to use Unicode or not - Catch will work with either setting.
+
+Next, add Catch to the 'includes':
+
+![VS2010 include options](VS2010options-include.png)
+
+...and change the debug runtime to be a Debug DLL:
+
+![VS2010 debug runtime options](VS2010options-debug-runtime.png)
+
+## Now write a test
+
+Next, delete the test code that the wizard provided in UnitTest1.cpp and write your own...
+
+
+![VS2010 build example](VS2010example-build.png)
+
+We can run this from the 'Test View' but be sure to select the option to 'Group By' Description if you want to see the Catch TEST_CASE names:
+
+![VS2010 example run](VS2010example-run.png)
+
+
+From here, double clicking on the failure takes you to the failure description as normal, where you get links to the code and the output of what happened...
+
+![VS2010 example description](VS2010example-desc.png)
+
+Now if you click the link for (in this case) "...unittest1.cpp: line 12" you get back to the problem:
+
+![VS2010 example fail](VS2010example-fail.png)
+
+And that's it!
+
+## Creating a Catch console project
+
+If you want to run Catch normally from the console, just create a new Windows Console app (you will need to turn off Unicode for this!) and add an additional .cpp file for `'main()'`.  I usually add a file called main.cpp, like this:
+
+```
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+``` 
+
+---
+
+[Home](../README.md)

docs/vs/VS2012managed-instructions.md

@@ -0,0 +1,63 @@
+Creating managed tests in VS2012 is very similar to creating tests in VS2010.
+
+[pre-requisite - obviously, you'll also need Catch - my copy is in C:\Projects\Phil\Catch in the following examples...and I'm using the normal, multiple include files.]
+
+## First, start by creating a new project
+
+Choose 'File' ==> 'New' ==> 'Project' and choose a new Visual C++ Managed Test project:
+![VS2012 test project](VS2012managed-test-project.png)
+
+Now we need to change some build options, so right click the project and choose 'Properties':
+
+First, in the 'General' options, change 'Common Language Runtime Support' to use basic clr:
+
+![VS2012 clr options](VS2012managed-options-clr.png)
+
+By default, Unicode will have been enabled - it is up to you whether to use Unicode or not - Catch will work with either setting.
+
+Next, add Catch to the 'includes':
+
+![VS2012 include options](VS2012managed-options-include.png)
+
+...and change the debug runtime to be a Debug DLL:
+
+![VS2012 debug runtime options](VS2012managed-options-debug-runtime.png)
+
+## Now write a test
+
+Next, delete the test code that the wizard provided in UnitTest.cpp and write your own...
+
+
+![VS2012 build example](VS2012managed-example-build.png)
+
+We can run this from the 'Test Explorer' but be sure to select the 'Traits' option from the drop down if you want to see the Catch TEST_CASE names:
+
+![VS2012 example run](VS2012managed-example-run.png)
+
+
+Sadly, VS2012 is not as intuitive as VS2010; from here you have top open up the failing test to get the failure information:
+
+![VS2012 example description](VS2012managed-example-desc.png)
+
+You can click the 'Output' link to see the output text:
+
+![VS2012 example description](VS2012managed-example-output.png)
+
+Now if you click the link at the top of the stack trace "...unittest.cpp: line 12" you get back to the problem:
+
+![VS2012 example fail](VS2012managed-example-fail.png)
+
+And that's it!
+
+## Creating a Catch console project
+
+If you want to run Catch normally from the console, just create a new Windows Console app (you will need to turn off Unicode for this!) and add an additional .cpp file for `'main()'`.  I usually add a file called main.cpp, like this:
+
+```
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+``` 
+
+---
+
+[Home](../README.md)

docs/vs/VS2012native-instructions.md

@@ -0,0 +1,57 @@
+Creating managed tests in VS2012 is very similar to creating managed tests.
+
+[pre-requisite - obviously, you'll also need Catch - my copy is in C:\Projects\Phil\Catch in the following examples...and I'm using the normal, multiple include files.]
+
+## First, start by creating a new project
+
+Choose 'File' ==> 'New' ==> 'Project' and choose a new Visual C++ Native Test project:
+![VS2012 test project](VS2012native-test-project.png)
+
+Now we need to change some build options, so right click the project and choose 'Properties':
+
+There's no CLR option this time of course, but by default, Unicode will have been enabled - it is up to you whether to use Unicode or not - Catch will work with either setting.
+
+Next, add Catch to the 'includes':
+
+![VS2012 include options](VS2012native-options-include.png)
+
+...and the wizard has correctly selected the debug runtime DLL.
+
+## Now write a test
+
+Next, delete the test code that the wizard provided in UnitTest1.cpp and write your own...
+
+
+![VS2012 build example](VS2012native-example-build.png)
+
+We can run this from the 'Test Explorer' but be sure to select the 'Traits' option from the drop down if you want to see the Catch TEST_CASE names:
+
+![VS2012 example run](VS2012native-example-run.png)
+
+
+Sadly, VS2012 is not as intuitive as VS2010; from here you have top open up the failing test to get the failure information:
+
+![VS2012 example description](VS2012native-example-desc.png)
+
+You can click the 'Output' link to see the output text:
+
+![VS2012 example description](VS2012native-example-output.png)
+
+Now if you click the link at the top of the stack trace "...unittest1.cpp: line 12" you get back to the problem:
+
+![VS2012 example fail](VS2012native-example-fail.png)
+
+And that's it!
+
+## Creating a Catch console project
+
+If you want to run Catch normally from the console, just create a new Windows Console app (you will need to turn off Unicode for this!) and add an additional .cpp file for `'main()'`.  I usually add a file called main.cpp, like this:
+
+```
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+``` 
+
+---
+
+[Home](../README.md)

docs/vs/vs-index.md

@@ -0,0 +1,51 @@
+Catch now supports integration with Visual Studio 2010 and 2012. It does this by redefining the macros to use existing VS features; whilst this isn't perfect, it seems to be a workable solution for those people who want to use the VS IDE, or for those who need to provide integration with CI systems that are able to process the test results generated by using MSBuild/test runner???.
+
+What does this mean? It means that (with a little care) you can use the same source code for regular Catch, Managed Catch projects in VS and Native Catch projects in VS2012, and you can run tests, see the results and 'click to go to the error' when a test fails.
+
+## VS2010 - Managed tests
+
+In VS2010 we can use the managed C++ tests created by the VS wizard - [see this page for instructions on how to do this](VS2010instructions)....
+
+...and you'll end up with something like this:
+![VS2010 failing test example](VS2010failingtest.png)
+
+(Note: the test is meant to fail!)
+
+## VS2012 - Managed and Native tests
+
+We can do the same for VS2012 - [see this page for instructions on how to do this for managed tests](VS2012managed-instructions) and [this page for native tests](VS2012native-instructions)....
+
+...and you'll end up with something like this:
+![VS2012 failing test example](VS2012failingtest.png)
+
+# Differences in behaviour 
+
+There are some minor differences in behaviour between Catch and Visual Studio projects; some are inevitable consequences of the 'run one test at a time' architecture of VS, whilst others are workarounds for 'features' in VS itself:
+
+* We can't hook directly into the test name architecture because Catch uses free form text for TEST_CASE names.
+* Catch tests always stop on first failure.
+* Tests in different modules may have name clashes.
+
+## TEST_CASE names
+
+You can still use the same names that you would normally use for Catch TEST_CASE names, however we use an internal name for the actual function name that the test lives in.  This means that you won't see the Catch names in the Test View (VS2010) unless you 'Group By' Description, or in VS2012 you select the 'Traits' view Test Explorer - see the screen shots above.
+ 
+## Catch tests always stop on first failure.
+
+A Catch test that uses SECTIONS will continue to run further sections if one fails; in VS this doesn't make much sense because in a visual environment we want to capture the context of where the test failed.  If we allowed the test to continue then we lose this context, so instead we always stop on each failure.  You can still use the CHECK macros if you don't want the test to stop.
+
+## Tests in different modules may have name clashes.
+
+In Native tests in VS2012, we have to create a Catch test case with a name that may clash with one in another module (.cpp file). If you put all your tests in a namespace that corresponds to the name of the file (e.g. ClassTest.cpp has tests in namespace ClassTests) then this never happens because the internal name that we assign is unique.  It would have been nice to have used an anonymous namespace but sadly if we do this then all the tests disappear from TestExplorer!  So we're stuck with the clashes; if you get a linker error like this:
+
+```
+1>VariadicMacrosTests.obj : error LNK2005: "void __cdecl
+ if_you_get_this_error_you_have_a_test_case_name_clash_please_put_a_namespace_around_the_test_case_at_line_23(void)"
+ (?if_you_get_this_error_you_have_a_test_case_name_clash_please_put_a_namespace_around_the_test_case_at_line_23@@YAXXZ)
+ already defined in MessageInstantiationTests2.obj
+```
+then you need to add/rename a namespace to avoid the clash.  
+
+---
+
+[Home](../README.md)