Difference between revisions of "NST JavaScript Unit Testing"

From NST Wiki
Jump to navigationJump to search
(Walk Through)
(Goals of JavaScript Unit Tests)
Line 18: Line 18:
 
* Verify that expected behaviors are supported by all supported browser environments.
 
* Verify that expected behaviors are supported by all supported browser environments.
 
* Be simple to run (simply loading: [http://nst.svn.sourceforge.net/viewvc/nst/trunk/include/javascript/test/TestSuite.html TestSuite.html] into your browser runs all of the unit tests for the NST project).
 
* Be simple to run (simply loading: [http://nst.svn.sourceforge.net/viewvc/nst/trunk/include/javascript/test/TestSuite.html TestSuite.html] into your browser runs all of the unit tests for the NST project).
 +
* Be usable by anyone wanting to unit test JavaScript code.
  
 
== What JavaScript Unit Tests Don't Do ==
 
== What JavaScript Unit Tests Don't Do ==

Revision as of 08:42, 26 January 2010

Overview

Over the years, we have accumulated numerous JavaScript functions and classes which we use as building blocks when creating the NST website (http://networksecuritytoolkit.org) and the web based user interface (NST WUI) for the Network Security Toolkit distribution.

As we rely on our core set of JavaScript building blocks to perform their tasks in a reliable manner, it became desirable to have a method which would allow us to quickly verify that these building blocks behaved in a consistent manner.

After being exposed to the power of the JUnit (http://junit.org/) unit testing framework for Java based code, we decided to create a unit testing framework for our JavaScript code.

The framework we came up with permits us (actually anyone) to quickly verify that various JavaScript functions and classes are behaving as expected simply by loading the following page into a web browser:

TestSuite.html

This Wiki page describes the conventions used in our JavaScript unit testing framework. This framework was designed such that it can be used outside of the NST development area (anyone with JavaScript code they would like to apply unit tests to is free to follow these conventions as well).

Goals of JavaScript Unit Tests

  • Verify expected behaviors of simple JavaScript functions and classes.
  • Verify that expected behaviors are supported by all supported browser environments.
  • Be simple to run (simply loading: TestSuite.html into your browser runs all of the unit tests for the NST project).
  • Be usable by anyone wanting to unit test JavaScript code.

What JavaScript Unit Tests Don't Do

  • Test service based behaviors (AJAX based features are difficult to unit test).
  • Test modifications to the active document (DOM changes are difficult to unit test).
  • Test visual renderings or appearance of rendered pages.

Requirements

Skills

Before proceeding with unit testing, it is recommended that you are familiar with:

  • Have a basic understanding of what unit testing means.
  • Using a web browser to load HTML pages directly from your file system.
  • Using a text editor to create and modify JavaScript code.
  • Have a basic understanding of JavaScript objects (creating classes) and the JavaScript prototype keyword.

Files/Directories

To add unit testing capabilities to a existing project, create a sub-directory named test and install the following files into it:

UnitTest.js
This file implements the JavaScript unit testing framework. All test cases you create for your JavaScript code will extend themselves from this class.
UnitTest.css
This file provides some style information for display the results of running the unit tests within a HTML page.
TestSuiteTemplate.html
This file can be saved as TestSuite.html. It will become the file you load into your web browser when you want to run your unit tests.
TestUnitTest.js
This file provides an example set of unit tests (for a function in the UnitTest.js file). You won't need this file in the long run, but it is loaded and run by the default TestSuiteTemplate.html template file.

Walk Through

The following section explains how to use the JavaScript unit testing framework by example.

In this example, the goal will be to test two JavaScript functions (each declared in their own file). The functions implemented are designed to behave similar to the basename and dirname commands one finds on many Unix systems.

Two JavaScript Source Files To Unit Test

The JavaScript files to be tested in these examples are minimal in size to help keep the instructions clear. In the real world, you would expect to see a lot more functions and classes defined in a single JavaScript file.

basename.js

Our example basename implementation can be downloaded from:

test/basename.js

dirname.js

Our example dirname implementation can be downloaded from:

dirname.js

Downloading and Installing JavaScript Unit Testing Support

Adding Unit Test Files

TestBaseName.js

test/TestBaseName.js

TestDirName.js

test/TestDirName.js

Updating The TestSuite.html File

You will need to edit the TestSuite.html file you downloaded in the following manner:

  • Find "STEP 1" in TestSuite.html and add
  • Remove the new TestUnitTest() entry in the test suite array (unless you want to leave this example unit test in your output).
  • You can also remove the inclusion of TestUnitTest.js and remove the TestUnitTest.js file.

Running The Unit Tests and Reviewing The Results

The following is what you should see if you've completed all of the steps in this walk through:

TestSuite.html

Notice that there is a failure in one of the unit tests. You can click on the links next to the failure to help drill down to the details of the failure.

When you drill down, you'll notice that the test failed because it expected the basename of "/var/log/" to be "log" and that the actual implementation produced "".

This error was left in the example to demonstrate the power of using unit tests to help eliminate ambiguity from your code. If you look at the source for this unit test, you notice a comment that indicates that the unit test wasn't really sure what the results should be when passing "/var/log/" to the basename function. At this point we can proceed to reconcile the discrepency by either updating the basename function to return "log" in this case, or updating the unit test to expect "" (we will need to decide what is the right decision).