Using NUnit with VB.NET

Instructions for installing nUnit with VB.NET

1. To start with you need to download nUnit. Once you have downloaded it install it using the default options; doing this really is the easiest option.

2. Start Visual Studio 2005 (this will work with VB.NET Express also, in exactly the same way).

3. Create a simple default WindowsApplication1 project consisting of a simple form: File|New Project, VisualBasic | Windows, WindowsApplication, OK. Compile and run using Ctrl-F5 and watch an empty form appear. Close it. Save the project (File|Save).

4. I recommend that you do Project|Show All Files. This will make the references appear in the solution explorer, which helps you see what you're doing.

5. Add a reference to nUnit to the project. In the 'Solutions Explorer' on the right hand side of the screen, right-click on WindowsApplication1, choose Add Reference. A dialog box will appear with several tabs; in the .NET tab, click on nunit.framework so that it is selected and click OK. The reference will appear in the Solutions Explorer.

6. Now add two classes in the usual way (in the 'Solutions Explorer' on the right hand side of the screen, right-click on WindowsApplication1, choose Add|Class. The two classes are AppSettings.vb and AppSettingsTests.vb. Paste the following code into each:

Imports NUnit.Framework

 _
Public Class AppSettingTests

  Private mAppSetting As AppSetting
  Private idval As String = "test234567"
  Private nameval As String = "test"

   _
  Public Sub SetUp()
      mAppSetting = New AppSetting(idval, nameval)
  End Sub

   _
  Public Sub TearDown()

      'nothing to do here
  End Sub

   _
  Public Sub id()
      Assert.AreSame(mAppSetting.id, idval, "ID value loaded was " & mAppSetting.id & " and not the expected value of : " & idval)
  End Sub

   _
  Public Sub name()
      Assert.AreSame(mAppSetting.name, nameval)
  End Sub
End Class

and

Public Class AppSetting
  Private displayName As String
  Private settingID As String
  Public Sub New(ByVal id As String, ByVal name As String)
      displayName = name
      settingID = id
  End Sub
  ReadOnly Property name() As String
      Get
          Return displayName
      End Get
  End Property
  ReadOnly Property id() As String
      Get
          Return settingID
      End Get
  End Property
  Public Overrides Function ToString() As String
      Return displayName
  End Function
End Class

7. Rebuild the exe with Ctrl-F5, check it still runs.

8. Now open a command line (Start|Run|cmd, enter), and cd to the bin directory in which that was compiled (in my case it was C:\myvbnet\WindowsApplication1\WindowsApplication1\bin\Release, but if you are running in debug mode it will be C:\myvbnet\WindowsApplication1\WindowsApplication1\bin\Debug). Do a dir and you should see something like this:

C:\myvbnet\WindowsApplication1\WindowsApplication1\bin\Release>dir
Volume in drive C has no label.
Volume Serial Number is 5472-A68F

Directory of C:\myvbnet\WindowsApplication1\WindowsApplication1\bin\Release

24/03/2007 11:25  .
24/03/2007 11:25  ..
16/03/2007 15:06 69,632 nunit.framework.dll
16/03/2007 15:06 279,779 nunit.framework.xml
24/03/2007 11:23 1,318 TestResult.xml
24/03/2007 11:19 1,463 TestTesult.xml
24/03/2007 11:25 28,672 WindowsApplication1.exe
24/03/2007 11:25 69,120 WindowsApplication1.pdb
24/03/2007 11:25 127 WindowsApplication1.xml
7 File(s) 450,111 bytes
2 Dir(s) 7,981,608,960 bytes free

C:\myvbnet\WindowsApplication1\WindowsApplication1\bin\Release>

By now this directory should contain not only your WindowsApplication1.exe but also nunit.framework.xml and nunit.framework.dll, copied there when you added the reference to them in VS. If these are not found you've probably forgotten to add the reference above.

9. Now double-click on the NUnit icon on your desktop to run the NUnit IDE. Do File|Open Project and navigate to the bin/release directory above. Click on the WindowsApplication1.exe. This should open, and display some tests:

10. Click on the Run button to run the tests. If this doesn't work, it's probably because (a) you forgot to recompile (b) you didn't include the reference so the .dll isn't there.

11. Now we can see that NUnit is working, we now check the command line version. Go back to your cmd window and run the following:

"C:\Program Files\NUnit 2.4\bin\nunit-console.exe" WindowsApplication1.exe

Something like this should happen:

C:\myvbnet\WindowsApplication1\WindowsApplication1\bin\Release>"C:\Program Files\NUnit 2.4\bin\nunit-console.exe" WindowsApplication1.exe
NUnit version 2.4.0
Copyright (C) 2002-2007 Charlie Poole.
Copyright (C) 2002-2004 James W. Newkirk, Michael C. Two, Alexei A. Vorontsov.
Copyright (C) 2000-2002 Philip Craig.
All Rights Reserved.

Runtime Environment -
OS Version: Microsoft Windows NT 5.1.2600 Service Pack 2
CLR Version: 2.0.50727.42 ( Net 2.0.50727.42 )

..
Tests run: 2, Failures: 0, Not run: 0, Time: 0.320 seconds



C:\myvbnet\WindowsApplication1\WindowsApplication1\bin\Release>

The command line tool is what you use from within VS.NET, which is why we check all this. If you get "Tests run: 0" you have again got something wrong; you probably are running the .exe from the .obj folder somehow.

12. Now return to VB.NET. You need to add a menu entry to run the command-line utility. Add this to the Tools menu as follows.

Open the "tools" menu and select the external tools option. This will pop up a small dialog box that lets you add/edit custom tools. By default in my version of VS 2005 one custom tool already existed (Dotfuscator) so I needed to add a new one. To do so you just click on the "Add" button.

Title:

nUnit
This can be anything.

Command:

C:\Program Files\NUnit-2.4\bin\nunit-console.exe

I used the browse button to find nunit-console.exe, if you installed in the default place it should be what I entered

Arguments

$(TargetName).exe

$(TargetPath) will NOT work.

Initial Directory

$(ProjectDir)/bin/release

$(TargetDir) will NOT work -- it tends to point to the obj directory

Since this setup is using the console option I also checked the "Use Output Window" checkbox.

For the "command" option you can also use the nunit-gui.exe if you want to see a nice graphical representation of test success/failure or just want to run certain tests; for the remainder of this article I will be referencing the console version but the gui version works just as well.

Once done entering my custom tool settings I hit the "OK" button.

This is where a lot of problems can occur. I am presuming that you are compiling to bin/release and that this is where your nunit.framework.dll and nunit.framework.xml are (do a search on the folder and find out). I have found that you cannot use $(TargetPath) since the blessed thing points to the obj/release folder rather than the bin/releasec:\echo.cmd text file containing only one line: folder. I diagnosed this by creating a simple

dir

adding this as a 'tool', running it and this showed where VS was really trying to run nUnit.

If you look at the Tools menu, an extra option 'nUnit' now appears. When you click on this, it runs the console nunit against your compiled exe and pipes the output to a box in VS.NET onscreen.

13. Now try running NUnit. If you now have a button give it a click, otherwise use Tools|nUnit. You will see some stuff appear in your "output" pane.

If a command window pops up instead that is becuase you didn't check "Use Output Window" when adding the custom tool. Go back and edit the custom tool, check that option, then click the button again. Eventually you should see some text appear in the output pane that looks something like this:

Tests run: 0, Failures: 0, Not run: 0, Time: 0.016 seconds

Or more likely

Runtime Environment -
OS Version: Microsoft Windows NT 5.1.2600 Service Pack 2
CLR Version: 2.0.50727.42 ( Net 2.0.50727.42 )

..
Tests run: 2, Failures: 0, Not run: 0, Time: 0.320 seconds

Since you have two tests in your project.

14. Now you're all set.

Troubleshooting

I spent hours getting this message:

This comes when you run nUnit from within the Visual Studio IDE in the wrong directory!!! I.e. when you defined the "External tool" above, you probably pointed it to $(TargetDir). The latter points to C:\myvbnet\WindowsApplication1\WindowsApplication1\obj\Release, which contains a .exe (just to fool you) but not the nunit.framework.dll and nunit.framework.xml files.

It gets even better. You can find that just after you add the reference to an existing project, clicking on nUnit seems to run but finds no tests.

Tests run: 0, Failures: 0, Not run: 0, Time: 0.016 seconds

But if you then recompile the project, it changes to the "Could not load file or assembly 'nunit.framework" error.

To fix this:

• Check whether you can run the tests using the NUnit GUI icon on your desktop, by navigating to your exe and opening that. If you can, it is certainly just a VS IDE configuration issue. If you cannot, I suggest you start using nunit-console in a CMD window as above, and diagnose things that way.
• Check what you have in the Tools|External Tools for nUnit. Have you inadvertantly edited a different entry? (I found this desperately easy to do by accident) Make sure that you are pointing to the right .exe in the right directory, with the nunit.framework.* files in it.

Optional Stuff

1. Optionally (don't bother with this until everything is working) you can also add an icon on the toolbar to run nUnit.

Return to the "tools" menu and pick "customize". Another dialog pops up that lets you create new toolbars and to put buttons on existing toolbars. Lets not worry about creating a new toolbar just for our nUnit button. Instead click on the "commands" tab then in the left pane (Categories) scroll down and select "tools". The right pane (Commands) will populate. Scroll through there until you find "External Command 2" (if your nUnit was the second custom command) and then drag that command onto any of your existing VS 2005 toolbars. Finally, click the close button on the dialog and you will see your new buttons label change to "nUnit" (or whatever you called this tool).

2. Do you want to keep your test classes separate from the source classes? Most of us do!

You don't have to let your .vb files sit where they are created. You can create a folder 'Source' under the project, drag the form1.vb to it, and the project will still work. This allows you to structure your files better. (There is also the argument that you ought to build separate 'assemblies' (i.e. dll's) rather than have one monster exe, but I haven't explored this).

I have created two folders: src and test-src. I put the AppSettings.vb in the first, and the AppSettingsTests.vb in the second. It works well, and the extra files don't clutter my main development area. This makes my project look like this:

3. Do you really want your test classes in the live exe? Probably not. If so, try to put them into a dll, in a separate project in the same solution.

(Note that I haven't really worked out how to do this yet!)

One difficulty is that the Solution (which owns the projects) is not shown by default in the above WindowsApplication1. This makes it hard to have multiple projects in the same solution. But this is merely an option on Tools|Options: