Monday, May 18, 2009

Introducing ASPUnitRunner

Have code in classic ASP? Want to write unit tests for it? Want to make it easy to run those tests?

Here’s my solution: ASPUnitRunner. It’s a .NET library that enables running ASPUnit tests via NUnit.

The Story

(If you don’t care about the “why”, skip this section.) I’ve been trying to get more into automated testing and TDD. But most of our code is written in classic ASP. I started writing some tests using the ASPUnit unit-testing framework for classic ASP. It does it’s job, but I found there was a little friction running the tests. You have to open a web browser, navigate to the right location and click Run Tests. And, continuous integration frameworks don’t exactly have out-of-the-box support for ASPUnit.

There are multiple options available: create an application shortcut for Google Chrome, write a script that uses cURL or wget, or setup Selenium or Watir tests like @calvinb. Any of these may work for you, but none of them were quite what I wanted.

I also found a refreshingly new series of posts on unit-testing classic ASP by Justin Davies. (You should really check them out if you’re interested in unit-testing classic ASP.) I had had the idea in my head to automate ASPUnit tests with NUnit, but he had already done it (albeit with his own unit testing framework). His articles inspired me and gave me some ideas, but it wasn’t until now that I actually wrote my own.

So I wrote my own library to allow running tests for the existing ASPUnit framework from the popular and easy-to-use NUnit test runner.

An Overview

ASPUnitRunner consists of two main classes: Runner and Results.

Runner’s constructor takes a URI to your ASPUnit test runner and an optional credentials parameter. You then call the Run method with the name of the ASPUnit test container to execute, which returns a Results object.

The Results object has the following properties: Tests, Errors, Failures and Details. You can use NUnit assertions to verify that there are zero errors and zero failures and display details if there were any errors or failures.

The source is available at github. If you come up with any improvements, let me know and I may integrate them.

How to Use

Note: the following instructions assume you have existing, runnable ASPUnit tests and are familiar with Visual Studio and NUnit.

  1. Verify that you are able to run your existing ASPUnit tests from a web browser.
  2. Create a new NUnit test project in Visual Studio.
  3. Download the latest ASPUnitRunner binaries and extract them.
  4. Add a new reference from your Visual Studio project to point to the DLL you just extracted in the last step.
  5. Create an NUnit test fixture similar to this example (note that it makes use of the Values attribute new to NUnit 2.5).
    • Add a using AspUnitFramework statement
    • Initialize a new Runner object with the URI for your ASPUnit test runner and optional credentials
    • Run the tests for each desired ASPUnit test container
    • Assert that the results has no Errors and no Failures.
  6. Compile
  7. Run the new tests using your favorite NUnit test runner (or integrate them into your NUnit-compatible continuous integration server).

Limitations

Unfortunately the NUnit GUI does not format the HTML result details well. I would like to improve this in the future.

I make no guarantees that this library won’t open a black hole and suck up your computer and the rest of the universe, nor that it won’t cause any other type of damage or loss.

Unlimitations

ASPUnitRunner is not actually dependent on NUnit. It should be usable from any .NET test framework.

In Conclusion

Other than some scripts and snippets, this is my first publicly released project of my own. Sure, it’s really small and simple—but it’s something.

Thanks to the creators of ASPUnit and NUnit for creating helpful tools and Justin Davies for the inspiring example.

I would love to hear any suggestions or feedback you have. Let me know if you find this useful. If you have questions getting it to work I’ll try to help as I can, but no guarantees.

2 comments:

  1. Excellent stuff Mike and I'm glad to see your project came to fruition.
    I'll definitely be checking out how you've implemented the NUnit work and if you need a contributor at any time if the project grows I'd love to help out, although my classic ASP work has dwindled away (thankfully!).
    It's great to see my posts providing some assitance... when you start blogging and have small random footfall you never know if they are read in full; it is fantastic to see them being useful to someone. I wish you luck in the future and I'll keep an eye on your work!

    ReplyDelete
  2. Thanks for the encouragement, Justin. Hopefully we'll move everything away from classic ASP eventually, too. But in the meantime, I figured I'd try to make it a little less painful ;-)

    ReplyDelete