Use XUnit to Run QUnit Tests

I read a great article recently about Unit testing JavaScript in VisualStudio with ReSharper, written by Chris Seroka. As cool as this feature is, it left me with two questions:

1. What about developers that do not have ReSharper?
2. How do I run my JavaScript unit tests on a builder server?

It is no secret that I, absolutely, love, xUnit! Thus I decided to extend xUnit theories to be able to run QUnit tests by implementing a new DataAttribute.

Introducing XUnit.PhantomQ

XUnit.PhantomQ is a little NuGet package you can install to get access to the QUnitDataAttribute (see below for an example). This library will allow you to execute your QUnit tests as XUnit tests.

XUnit.PhantomQ supports both library and web projects, and features the ability to easily specify test files and their dependencies by real relative path to the root of your project.

XUnit.PhantomQ on NuGet
XUnit.PhantomQ Source on GitHub

QUnitData Attribute

Here is an example of writing some JavaScript, a file of QUnit tests, and then using an xUnit theory and a QUnitData Attribute to execute all of those tests right inside of Visual Studio.

// Contents of Demo.js

function getFive() {

    return 5;

}

// Contents of Tests.js

test('Test Five', function() {

    var actual = getFive();

    equal(actual, 5);

});

test('Test Not Four', function () {

    var actual = getFive();

    notEqual(actual, 4);

});

// Contents of QUnitTests.cs

public class QUnitTests

{

    [Theory, QUnitData("Tests.js", "Demo.js")]

    public void ReturnFiveTests(QUnitTest test)

    {

        test.AssertSuccess();

    }

}

Integrating XUnit, PhantomJS, and QUnit

So, how does this thing work under the hood? Below is the complete pipeline, step by step, of whenever the tests are executed:

1. The XUnit test runner identifies your theory tests.
2. The QUnitDataAttribute is invoked.
3. A static helper locates PhantomJS.exe and the root folder of your project.
   • It will automatically walk up the folder structure and try to find PhantomJS.exe in your packages folder. However, you can override this and explicitly set the full path by adding an AppSetting to your config file:
     <add key="PhantomQ.PhantomJsExePath" value="C:/PhantomJS.exe" />
   • The same goes for the root of your project, you can override this location with another AppSetting to your config:
     <add key="PhantomQ.WorkingDirectory" value="C:/Code/DemoProject" />
4. PhantomJS.exe is invoked as a separate process.
5. The server loads up XUnit.PhantomQ.Server.js
6. The server now opens XUnit.PhantomQ.html
7. QUnit is set to autoRun false.
8. Event handlers are added to QUnit for testDone and done.
9. All of the dependencies are now added to the page as script tags.
10. The test file itself is loaded.
11. QUnit.start is invoked.
12. The server waits for the test to complete.
13. Upon completion the server reads the results out of the page.
14. The tests and their results are serialized to a JSON dictionary.
15. The result dictionary is written to the standard output.
16. The resulting JSON string is read in from the process output.
17. The results are deserialized using Newtonsoft.JSON
18. The results are loaded into QUnitTest objects.
19. The QUnitTest array is passed back from the DataAttribute
20. Each test run finally calls the AssertSuccess and throws on failure.

...and that's (finally) all folks! If you have any questions, comments, or thoughts on how this could be improved, please let me know!

Enjoy,
Tom