Running Visual Studio 2005 on a Windows Vista platform, the documentation on the NUnit project web site was a bit anemic and left me perplexed. I posted my notes and experience here to help the next programmer who falls into the same trap of using inadequate documentation and having no previous experience with the product.
Getting started with the NUnit testing framework was rather like touching an electrified fence: the shock certainly woke me up. Now, don't think I don't like the package and the effort that went into it. I certainly want to thank the authors for putting together a very useful software framework that improves the quality of my code. On the other hand, it would be nicer if it were easier to get working or at least had some accurate installation instructions somewhere. To the best of my ability, here are those instructions.
The download page was pretty clear about what package you should use. Since I wanted to install on Windows and wasn't going to be developing NUnit itself, I picked the Windows binary Installer package. At the time this article was written, NUnit 2.5.3 was the current production release, so I downloaded the "win" installation archive,
NUnit-188.8.131.5245.msi, and ran it on my development machine. I picked the
Typicalinstallation and got what I thought I needed. Seemed simple enough.
Following the text on the Installation page, I got to the Configuration section (about half a page) before the fog started setting in. The document mentions the configuration files are different depending on the NUnit executable you run. Personally I think this belongs in a different section of the document, but I could go back and look at it again later, so I just overlooked it for now.
The Installation Verification really threw me for a loop. It states:
Verify that the installation has worked successfully by running the NUnit gui and loading and running NUnitTests.nunit. All tests should pass.
Warning! Misleading Documentation Alert! OK, it's elementary that I can run the GUI NUnit by going to
Start->NUnit 2.5.3->NUnit. Now I just needed to find
NUnitTests.nunit. No dice. After searching fruitlessly through every folder the installer created, I deduced that somebody simply forgot to include the file in the installer archive. Oh well, mistakes happen. I went back to the web site and downloaded the previous version. Uninstalled 2.5.3 and installed 2.5.2. *#&*@^! Same problem. The file didn't exist in either of the latest packages, so I thought. Grrr!
After a brief email exchange with the project administrator, Charlie Poole, it turns out that performing the Typical install, the file is not available. Only if you install the Unit Tests for NUnit under .NET 1.1 does the noted file get installed. This is confusing and a revision of the documentation or installer is under consideration. I have to say this was very responsive and indicative of the quality of the package as I saw so far.
Well, I just skipped the verification and tried one of the samples. Curiously, there were no
*.nunitfiles to be found anywhere. Maybe they were just for the GUI? I hadn't found it in the documentation so I moved on to compile a sample.
I use C# most of the time, so I used one of those samples. The
samples\csharpdirectory contained several different tests organized under what appears to be a Visual Studio Solution so I opened
CSharp.sln. OK, VS had to convert it to my version, so I let it and it didn't complain. Built the solution and got an error in
The type or namespace name 'Framework' does not exist in the namespace 'NUnit' (are you missing an assembly reference?)
I checked the references; no, it was there. But there was a warning label on the icon. Looking at its properties, the reference had no path and no version!
Now was Visual Studio giving me problems? I clicked on the project icon, added the reference again - at least I was able to pick it off the .NET reference list. It was named
NUnit.Framework, so that didn't look right. But, no change, the reference still showed the warning label. @$#@#&%#@!
I removed the existing reference and added the reference again. Now it sorta looked right that the warning label was gone. Build, and the projects were compiled. I launched the NUnit GUI application. Selected
Open Project...and browsed to the
csharp/moneydirectory. Nothing. Really? No, nothing. Drilled down into
bin/Debugand find a couple
.dllfiles, but still no
*.nunitfiles. Tried loading the
cs-money.dllassembly directly and I saw the tree of tests. That was promising. So I clicked the
Runbutton and a green progress bar filled the status area.
Success!? Yes, no, maybe? Yes, I'll call it success.
My suspicion was the
.dllassembly contained all the information an NUnit project file would have, but I didn't locate the documentation to prove it. Trial and error is a heck of a poor way to find out. Moral: bad documentation doesn't make for good testing. Your mileage may vary :-/.
Here's the short version of all this:
- Download the NUnit installer package.
- Run the installer.
- Skip the Installation Verification step because the files weren't installed.
- To create and use NUnit tests with a new project, add a reference to the
nunit.framework.dlllibrary to the project.
- To use NUnit with the sample projects, remove the existing
nunit.framework.dlllibrary references first. Add a reference to the newly installed library to the projects.
- Don't bother looking for
*.nunitfiles. Or do a full install.
It's difficult to be grateful when you're annoyed. But at least I was running and demonstrated the framework will actually do what it's told, once I figured that out.