If you use NUnit for testing your .NET DLLs, you’re already familiar with either NUnit.exe (GUI runner) or NUnit-console.exe (command line runner). These “runner” applications provide a harness that loads your test DLLs, finds the test methods, executes them, and reports the results. Because these test methods are just like any other application code, you may find yourself needing to step through them using the Visual Studio debugger. So how do we do this?
Without making any changes to your .NET project, it’s possible to have Visual Studio attach to the NUnit runner application, allowing you to hit breakpoints and step through your code. For example, if you’re using the NUnit GUI runner, the steps are as follows:
- Build a debug version the test DLLs using Visual Studio.
- Launch the NUnit.exe GUI runner from Windows Explorer.
- Click File | Open… and select and open your test DLL.
- In Visual Studio, click Debug | Attach to Process…
- In the list of available processes, find and select NUnit.exe. (NOTE: If your DLL is built for the .NET 4.0 Framework, see the .NET 4.0 Assemblies section after going through the section below for additional instructions.)
- Set a breakpoint in your test code.
- Back in the NUnit GUI runner, select and run the appropriate test method to be debugged. Visual Studio should hit your breakpoint.
This is pretty handy, but it would be even handier if we could just launch straight into the NUnit runner when we hit F5 (Debug | Start Debugging…) inside Visual Studio. So, let’s set it up…
- In Visual Studio, open your test DLL project by right-clicking the project in the Solution Explorer and selecting Properties (or by selecting the Project | [test DLL name] Properties… menu option).
- On the Debug tab, select the Start external program radio button in the Start Action section.
- In the edit box, enter the path to the NUnit.exe runner application (or NUnit-console.exe to run the console runner).
- In the Command line arguments edit box in the Start Options section, enter the file name of the test DLL.
- Make sure your test DLL project is set as the startup project by right-clicking on the project in the Solution Explorer and selecting Set as Startup Project.
- Hit F5 to launch NUnit, select and run the appropriate test method to be debugged, and enjoy the debugging goodness.
.NET 4.0 Assemblies
If your test DLLs are written for .NET 4.0, there’s some extra work involved. The steps above alone are not enough to enable debugging. Although NUnit will be launched when debugging is started, Visual Studio will not hit any breakpoints. This is because NUnit launches a second application domain (nunit-agent.exe) where the test DLL’s methods are executed. This is done because NUnit itself is a .NET 2.0 application and therefore by default runs in a .NET 2.0 application domain. Since .NET 4.0 test DLLs require a .NET 4.0 application domain, NUnit must launch this secondary domain in order to execute the test methods. Using Visual Studio’s “attach to process” method that we used above to attach to nunit-agent.exe, we can once again enable debugging. However, our goal is to launch straight into debugging from Visual Studio. So, is there a workaround to this problem? Yes.
Although by default .NET will launch an application using the same version of the Framework for which the application was originally targeted, it also allows us to override this behavior and force the application to be launched with a different version of the Framework. If we were to force NUnit to run using the 4.0 Framework, it wouldn’t need to launch a separate application domain to load and execute our test DLLs, which should then allow us to hit our breakpoints. To do this, we just need to add the following to the nunit.exe.config file (or nunit-console.exe.config file for the console runner), which is located in the same folder as nunit.exe.
Under <configuration>, add:
<startup> <supportedRuntime version="v4.0.30319" /> </startup>
Under <runtime>, add:
<loadFromRemoteSources enabled="true" />
The first setting forces NUnit to launch using the 4.0 Framework while the second setting instructs the 4.0 Framework to allow NUnit to load any remote DLLs specified that by default would not otherwise be loaded in 4.0 due to differences in CAS policy implementations between the 4.0 Framework and earlier versions.
With these settings in place, you now have F5 debugging support for your NUnit test DLLs regardless of their .NET Framework version.
Now, go have some cake!