Modern
ASP.
NET web applications take full advantage of client-side JavaScript
to provide better interactivity and responsiveness. If you are building an
ASP.
NET application in the right way, you quickly end up with lots and lots of JavaScript code. When writing server code, you should be writing unit tests. One big advantage of unit tests is that they provide you with a safety
net that enable you
to safely modify your existing code – for example, fix bugs, add new features, and make performance enhancements -- without breaking your existing code. Every time you modify your code, you can execute your unit tests
to verify that you have not broken anything. For the same reason that you should write unit tests for your server code, you should write unit tests for your client code. JavaScript is just as susceptible
to bugs as C#. There is no shortage of unit testing frameworks for JavaScript. Each of the major JavaScript libraries has its own unit testing framework. For example, jQuery has QUnit, Prototype has UnitTestJS, YUI has YUI Test, and Dojo has Dojo Objective Harness (DOH). The challenge is integrating a JavaScript unit testing framework with Visual Studio. Visual Studio and Visual Studio ALM provide fantastic support for server-side unit tests. You can easily view the results of running your unit tests in the Visual Studio Test Results window. You can set up a check-in policy which requires that all unit tests pass before your source code can be committed
to the source code repository. In addition, you can set up Team Build
to execute your unit tests automatically. Unfortunately, Visual Studio does not provide “out-of-the-box” support for JavaScript unit tests. MS Test, the unit testing framework included in Visual Studio, does not support JavaScript unit tests. As soon as you leave the server world, you are left on your own. The goal of this blog entry is
to describe one approach
to integrating JavaScript unit tests with MS Test so that you can execute your JavaScript unit tests side-by-side with your C# unit tests. The goal is
to enable you
to execute JavaScript unit tests in exactly the same way as server-side unit tests. You can download the source code described by this project by scrolling
to the end of this blog entry. Rejected Approach: Browser Launchers One popular approach
to executing JavaScript unit tests is
to use a browser as a test-driver. When you use a browser as a test-driver, you open up a browser window
to execute and view the results of executing your JavaScript unit tests. For example, QUnit – the unit testing framework for jQuery – takes this approach. The following HTML page illustrates how you can use QUnit
to create a unit test for a
function named addNumbers(). <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Using QUnit</title>
<link rel="stylesheet" href="http://github.com/jquery/qunit/raw/master/qunit/qunit.css" type="text/css" />
</head>
<body>
<h1 id="qunit-header">QUnit example</h1>
<h2 id="qunit-banner"></h2>
<div id="qunit-testrunner-toolbar"></div>
<h2 id="qunit-userAgent"></h2>
<ol id="qunit-tests"></ol>
<div id="qunit-fixture">test markup, will be hidden</div>
<script type="text/javascript" src="http://code.jquery.com/jquery-latest.js"></script>
<script type="text/javascript" src="http://github.com/jquery/qunit/raw/master/qunit/qunit.js"></script>
<script type="text/javascript">
// The
function to test
function addNumbers(a, b) {
return a+b;
}
// The unit test
test("Test of addNumbers",
function () {
equals(4, addNumbers(1,3), "1+3 should be 4");
});
</script>
</body>
</html>
This test verifies that calling addNumbers(1,3) returns the expected value 4. When you open this page in a browser, you can see that this test does, in fact, pass.
The idea is that you can quickly refresh this QUnit HTML JavaScript test driver page in your browser whenever you modify your JavaScript code. In other words, you can keep a browser window open and keep refreshing it over and over while you are developing your application. That way, you can know very quickly whenever you have broken your JavaScript code.
While easy
to setup, there are several big disadvantages
to this approach
to executing JavaScript unit tests:
You must view your JavaScript unit test results in a different location than your server unit test results. The JavaScript unit test results appear in the browser and the server unit test results appear in the Visual Studio Test Results window. Because all of your unit test results don’t appear in a single location, you are more likely
to introduce bugs into your code without noticing it.
Because your unit tests are not integrated with Visual Studio – in particular, MS Test -- you cannot easily include your JavaScript unit tests when setting up check-in policies or when performing automated builds with Team Build.
A more sophisticated approach
to using a browser as a test-driver is
to automate the web browser. Instead of launching the browser and loading the test code yourself, you use a framework
to automate this process. There are several different testing frameworks that support this approach:
· Selenium – Selenium is a very powerful framework for automating browser tests. You can create your tests by recording a Firefox session or by writing the test driver code in server code such as C#. You can learn more about Selenium at http://seleniumhq.org/.
LTAF – The
ASP.
NET team uses the Lightweight Test Automation Framework
to test JavaScript code in the
ASP.
NET framework. You can learn more about LTAF by visiting the project home at CodePlex: http://aspnet.codeplex.com/releases/view/35501
jsTestDriver – This framework uses Java
to automate the browser. jsTestDriver creates a server which can be used
to automate multiple browsers simultaneously. This project is located at http://code.google.com/p/js-test-driver/
TestSwam – This framework, created by John Resig, uses PHP
to automate the browser. Like jsTestDriver, the framework creates a test server. You can open multiple browsers that are automated by the test server. Learn more about TestSwarm by visiting the following address: https://github.com/jeresig/testswarm/wiki
Yeti – This is the framework introduced by Yahoo for automating browser tests. Yeti uses server-side JavaScript and depends on Node.js. Learn more about Yeti at http://www.yuiblog.com/blog/2010/08/25/introducing-yeti-the-yui-easy-testing-interface/
All of these frameworks are great for integration tests – however, they are not the best frameworks
to use for unit tests. In one way or another, all of these frameworks depend on executing tests within the context of a “living and breathing” browser.
If you create an
ASP.
NET Unit Test then Visual Studio will launch a web server before executing the unit test. Why is launching a web server so bad? It is not the worst thing in the world. However, it does introduce dependencies that prevent your code from being tested in isolation. One of the defining features of a unit test -- versus an integration test – is that a unit test tests code in isolation.
Another problem with launching a web server when performing unit tests is that launching a web server can be slow. If you cannot execute your unit tests quickly, you are less likely
to execute your unit tests each and every time you make a code change. You are much more likely
to fall into the pit of failure.
Launching a browser when performing a JavaScript unit test has all of the same disadvantages as launching a web server when performing an
ASP.
NET unit test. Instead of testing a unit of JavaScript code in isolation, you are testing JavaScript code within the context of a particular browser.
Using the frameworks listed above for integration tests makes perfect sense. However, I want
to consider a different approach for creating unit tests for JavaScript code.
Using Server-Side JavaScript for JavaScript Unit Tests
A completely different approach
to executing JavaScript unit tests is
to perform the tests outside of any browser. If you really want
to test JavaScript then you should test JavaScript and leave the browser out of the testing process.
There are several ways that you can execute JavaScript on the server outside the context of any browser:
Rhino – Rhino is an implementation of JavaScript written in Java. The Rhino project is maintained by the Mozilla project. Learn more about Rhino at http://www.mozilla.org/rhino/
V8 – V8 is the open-source Google JavaScript engine written in C++. This is the JavaScript engine used by the Chrome web browser. You can download V8 and embed it in your project by visiting http://code.google.com/p/v8/
JScript – JScript is the JavaScript Script Engine used by Internet Explorer (up
to but not including Internet Explorer 9), Windows Script Host, and Active Server Pages.
Internet Explorer is still the most popular web browser. Therefore, I decided
to focus on using the JScript Script Engine
to execute JavaScript unit tests.
Using the Microsoft Script Control
There are two basic ways that you can pass JavaScript
to the JScript Script Engine and execute the code: use the Microsoft Windows Script Interfaces or use the Microsoft Script Control.
The difficult and proper way
to execute JavaScript using the JScript Script Engine is
to use the Microsoft Windows Script Interfaces. You can learn more about the Script Interfaces by visiting http://msdn.microsoft.com/en-us/library/t9d4xf28(VS.85).aspx
The main disadvantage of using the Script Interfaces is that they are difficult
to use from .
NET. There is a great series of articles on using the Script Interfaces from C# located at http://www.drdobbs.com/184406028.
I picked the easier alternative and used the Microsoft Script Control. The Microsoft Script Control is an ActiveX control that provides a higher level abstraction over the Window Script Interfaces.
You can download the Microsoft Script Control from here:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=d7e31492-2595-49e6-8c02-1426fec693ac
After you download the Microsoft Script Control, you need
to add a reference
to it
to your project. Select the Visual Studio menu option Project, Add Reference
to open the Add Reference dialog. Select the COM tab and add the Microsoft Script Control 1.0.
Using the Script Control is easy. You call the Script Control AddCode() method
to add JavaScript code
to the Script Engine. Next, you call the Script Control Run() method
to run a particular JavaScript
function.
The reference documentation for the Microsoft Script Control is located at the MSDN website:
http://msdn.microsoft.com/en-us/library/aa227633%28v=vs.60%29.aspx
Creating the JavaScript Code
to Test
To keep things simple, let’s imagine that you want
to test the following JavaScript
function named addNumbers() which simply adds two numbers together:
MvcApplication1\Scripts\Math.js
function addNumbers(a, b) {
return 5;
}
Notice that the addNumbers() method always returns the value 5. Right-now, it will not pass a good unit test.
Create this file and save it in your project with the name Math.js in your MVC project’s Scripts folder (Save the file in your actual MVC application and not your MVC test application).
Creating the JavaScript Test Helper Class
To make it easier
to use the Microsoft Script Control in unit tests, we can create a helper class. This class contains two methods:
LoadFile() – Loads a JavaScript file. Use this method
to load the JavaScript file being tested or the JavaScript file containing the unit tests.
ExecuteTest() – Executes the JavaScript code. Use this method
to execute a JavaScript unit test.
Here’s the code for the JavaScriptTestHelper class:
JavaScriptTestHelper.cs
using System;
using System.IO;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using MSScriptControl;
namespace MvcApplication1.Tests {
public class JavaScriptTestHelper : IDisposable {
private ScriptControl _sc;
private TestContext _context;
/// <summary>
/// You need
to use this helper with Unit Tests and not
/// Basic Unit Tests because you need a Test Context
/// </summary>
/// <param name="testContext">Unit Test Test Context</param>
public JavaScriptTestHelper(TestContext testContext) {
if (testContext == null) {
throw new ArgumentNullException("TestContext");
}
_context = testContext;
_sc = new ScriptControl();
_sc.Language = "JScript";
_sc.AllowUI = false;
}
/// <summary>
/// Load the contents of a JavaScript file into the
/// Script Engine.
/// </summary>
/// <param name="path">Path
to JavaScript file</param>
public void LoadFile(string path) {
var fileContents = File.ReadAllText(path);
_sc.AddCode(fileContents);
}
/// <summary>
/// Pass the path of the test that you want
to execute.
/// </summary>
/// <param name="testMethodName">JavaScript
function name</param>
public void ExecuteTest(string testMethodName) {
dynamic result = null;
try {
result = _sc.Run(testMethodName, new object[] { });
} catch {
var error = ((IScriptControl)_sc).Error;
if (error != null) {
var description = error.Description;
var line = error.Line;
var column = error.Column;
var text = error.Text;
var source = error.Source;
if (_context != null) {
var details = String.Format("{0} \r\nLine: {1} Column: {2}", source, line, column);
_context.WriteLine(details);
}
}
throw new AssertFailedException(error.Description);
}
}
public void Dispose() {
_sc = null;
}
}
}
Notice that the JavaScriptTestHelper class requires a Test Context
to be instantiated. For this reason, you can use the JavaScriptTestHelper only with a Visual Studio Unit Test and not a Basic Unit Test (These are two different types of Visual Studio project items).
Add the JavaScriptTestHelper file
to your MVC test application (for example, MvcApplication1.Tests).
Creating the JavaScript Unit Test
Next, we need
to create the JavaScript unit test
function that we will use
to test the addNumbers()
function. Create a folder in your MVC test project named JavaScriptTests and add the following JavaScript file
to this folder:
MvcApplication1.Tests\JavaScriptTests\MathTest.js
/// <reference path="JavaScriptUnitTestFramework.js"/>
function testAddNumbers() {
// Act
var result = addNumbers(1, 3);
// Assert
assert.areEqual(4, result, "addNumbers did not return right value!");
}
The testAddNumbers()
function takes advantage of another JavaScript library named JavaScriptUnitTestFramework.js. This library contains all of the code necessary
to make assertions. Add the following JavaScriptnitTestFramework.js
to the same folder as the MathTest.js file:
MvcApplication1.Tests\JavaScriptTests\JavaScriptUnitTestFramework.js
var assert = {
areEqual:
function (expected, actual, message) {
if (expected !== actual) {
throw new Error("Expected value " + expected
+ " is not equal
to " + actual + ". " + message);
}
}
};
There is only one type of assertion supported by this file: the areEqual() assertion. Most likely, you would want
to add additional types of assertions
to this file
to make it easier
to write your JavaScript unit tests.
Deploying the JavaScript Test Files
This step is non-intuitive. When you use Visual Studio
to run unit tests, Visual Studio creates a new folder and executes a copy of the files in your project. After you run your unit tests, your Visual Studio Solution will contain a new folder named TestResults that includes a subfolder for each test run.
You need
to configure Visual Studio
to deploy your JavaScript files
to the test run folder or Visual Studio won’t be able
to find your JavaScript files when you execute your unit tests. You will get an error that looks something like this when you attempt
to execute your unit tests:
You can configure Visual Studio
to deploy your JavaScript files by adding a Test Settings file
to your Visual Studio Solution. It is important
to understand that you need
to add this file
to your Visual Studio Solution and not a particular Visual Studio project. Right-click your Solution in the Solution Explorer window and select the menu option Add, New Item. Select the Test Settings item and click the Add button.
After you create a Test Settings file for your solution, you can indicate that you want a particular folder
to be deployed whenever you perform a test run. Select the menu option Test, Edit Test Settings
to edit your test configuration file. Select the Deployment tab and select your MVC test project’s JavaScriptTest folder
to deploy.
Click the Apply button and the Close button
to save the changes and close the dialog.
Creating the Visual Studio Unit Test
The very last step is
to create the Visual Studio unit test (the MS Test unit test). Add a new unit test
to your MVC test project by selecting the menu option Add New Item and selecting the Unit Test project item (Do not select the Basic Unit Test project item):
The difference between a Basic Unit Test and a Unit Test is that a Unit Test includes a Test Context. We need this Test Context
to use the JavaScriptTestHelper class that we created earlier.
Enter the following test method for the new unit test:
[TestMethod]
public void TestAddNumbers() {
var jsHelper = new JavaScriptTestHelper(this.TestContext);
// Load JavaScript files
jsHelper.LoadFile("JavaScriptUnitTestFramework.js");
jsHelper.LoadFile(@"..\..\..\MvcApplication1\Scripts\Math.js");
jsHelper.LoadFile("MathTest.js");
// Execute JavaScript Test
jsHelper.ExecuteTest("testAddNumbers");
}
This code uses the JavaScriptTestHelper
to load three files:
JavaScripUnitTestFramework.js – Contains the assert functions.
Math.js – Contains the addNumbers()
function from your MVC application which is being tested.
MathTest.js – Contains the JavaScript unit test
function.
Next, the test method calls the JavaScriptTestHelper ExecuteTest() method
to execute the testAddNumbers() JavaScript
function.
Running the Visual Studio JavaScript Unit Test
After you complete all of the steps described above, you can execute the JavaScript unit test just like any other unit test. You can use the keyboard combination CTRL-R, CTRL-A
to run all of the tests in the current Visual Studio Solution. Alternatively, you can use the buttons in the Visual Studio toolbar
to run the tests:
(Unfortunately, the Run All Impacted Tests button won’t work correctly because Visual Studio won’t detect that your JavaScript code has changed. Therefore, you should use either the Run Tests in Current Context or Run All Tests in Solution options instead.)
The results of running the JavaScript tests appear side-by-side with the results of running the server tests in the Test Results window. For example, if you Run All Tests in Solution then you will get the following results:
Notice that the TestAddNumbers() JavaScript test has failed. That is good because our addNumbers()
function is hard-coded
to always return the value 5.
If you double-click the failing JavaScript test, you can view additional details such as the JavaScript error message and the line number of the JavaScript code that failed:
Summary
The goal of this blog entry was
to explain an approach
to creating JavaScript unit tests that can be easily integrated with Visual Studio and Visual Studio ALM. I described how you can use the Microsoft Script Control
to execute JavaScript on the server. By taking advantage of the Microsoft Script Control, we were able
to execute our JavaScript unit tests side-by-side with all of our other unit tests and view the results in the standard Visual Studio Test Results window.
You can download the code discussed in this blog entry from here:
http://StephenWalther.com/downloads/Blog/JavaScriptUnitTesting/JavaScriptUnitTests.zip
Before running this code, you need
to first install the Microsoft Script Control which you can download from here:
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=d7e31492-2595-49e6-8c02-1426fec693ac
