running javascript unit tests as part of a CI Build - qUnit and phantomJs

here is one way to have javascript unit tests run as part of a CI (Continuous Integration) build.
________________________________________________
Summary

With a simple Windows BAT script, we can run the qUnit unit tests from the command line using PhantomJs, and detect when 1 or more tests failed.

In this way, we can force a build to fail, whenever tests are failing.

________________________________________________
Dependencies:
You can download and unzip these dependencies, and add them into source control.
_____________________________
PhantomJs
phantomJs 1.7.0
https://github.com/ariya/phantomjs

PhantomJs is a 'headless web browser' which basically means it is a tool that lets you run javascript from the command line, without the need for a full blown browser.

_____________________________
qUnit
qUnit 1.10.0 

http://qunitjs.com/

qUnit is a javascript unit testing library.
Out of the box, qUnit lets you run javascript unit tests, by manually opening a HTML file, and inspecting the output.
________________________________________________
File Structure:
This is the file structure I use.
If you need to use a different structure, then you will need to modify the BAT scripts that follow below.

js
└───UnitTests  
   └───3rdParty  
     ├───PhantomJS  
     │  └───phantomjs-1.7.0-windows  
     │    └───examples  
     └───qUnit  
       └───examples  

________________________________________________
Windows BAT script to run the unit tests:

 @ECHO OFF  
 SETLOCAL  
 pushd js\UnitTests  
 SET PATH_TO_PHANTOM=3rdParty\PhantomJS\phantomjs-1.7.0-windows\  
 call "%PATH_TO_PHANTOM%\phantomjs.exe" "%PATH_TO_PHANTOM%\examples\run-qunit.js"     "MapModelTests.html?noglobals=true"  
 if %ERRORLEVEL% NEQ 0 (GOTO ERROR_OCCURRED)  
 GOTO DONE  
 :ERROR_OCCURRED  
 error_occurred!  
 :DONE  
 popd  

note: here we assume that the qUnit HTML test file is named 'MapModelTests.html'.

Save this BAT script as runUnitTests.bat in the top directory of the relevant project.
________________________________________________
Adding the unit tests to the build (Visual Studio)

In Visual Studio, create a Unit Test project for the web site project.
Visual Studio will produce a Unit Test project, with one empty test.
Rename this test to be TestCompilesOk.

In Visual Studio, right click on the project and select Properties.
Select Post Build.
Add a post build step, to execute the BAT script, and to detect if an error occurred:

 call $(ProjectDir)\..\MyProject\runUnitTests.bat  
 if %ERRORLEVEL% NEQ 0 (GOTO ERROR_OCCURRED)  
 GOTO DONE  
 :ERROR_OCCURRED  
 error_occurred!  
 :DONE  

________________________________________________
Congratulations! the javascript tests now run with every build

Now, each time the *test* project is built, the javascript unit tests will be run.

Note: it is good to have the javascript tests run on a separate *test* project,
because if the javascript tests fail, you still need to be able to deploy your web project,
in order to diagnose the test failures.

Assuming that you have a CI build running to build your project, then the javascript unit tests will now also run with the CI build.

Setting up a CI build in TFS is outside of the scope of this blog -
but here is a link that may help:

Set Up Continuous Integration with Team Foundation Server
http://msdn.microsoft.com/en-us/library/hh395023.aspx


________________________________________________

weakness with this approach: browser specific javascript support is not tested

note: a weakness with this approach, is that the javascript is not being run in any widely used browser.

However, an argument for this approach, is that successfully passing unit test runs are essential to a CI build.

Testing specific browsers is a more like an integration test, which should be done in addition and not in place of CI testing.