This project is read-only.

Documentation

JSTest has a small public API, so using JSTest is simple and straight forward. See below for
  • Important Notes
  • Debugging Instructions
  • TestScript class API
  • Assert class API

Moved to GitHub Wiki

Latest Documentation Available on https://github.com/cbaxter/JSTest.NET/wiki

Important Notes

By default the test script timeout is 10 seconds; however when running inside the debugger, this timeout is removed. As such, it is not recommended to simply ignore the request to lauch the "Visual studio Just-In-Time Debugger" as any infinite loops (which your code will never have) will leave a CScript process running in the background that must be manually killed.

CScript does not allow functions explicitly added to the WScript object to be invoked (will result in an Access Violation). If you must define global functions it is required that you use a traditional approach of declaring a global function as shown below.

// CScript Global Function
function myGlobalFunction() {
    // Function Code
}

myGlobalFunction(); 

// CScript Access Violation
this.myGlobalFunction() {
    // Function Code
}
An alternative option would be to declare your own window object reference and explicitly attach to the window object.

Debugging

Debugging with JSTest couldn't be easier. Simply launch the unit test in question with the Visual Studio debugger and you will be prompted to launch the Visual studio Just-In-Time Debugger to debug and step through your JavaScript unit test.

Launch Visual Studio Debugger
Launch.png

Step Through and Debug Test Script
JITD.png

TestScript Class

The TestScript class is the core of JSTest. The TestScript class wraps a CScript command and is the test runner for each JavaScript unit test.
Constructors
TestScript exposes two public constructors. The default public constructor sets a script timeout of ten seconds. Alternatively, you may use the overloaded constructor to specifcy a custom timeout for any given JavaScript unit test.

    public TestScript();                                 // Defaults script timeout to 10 seconds
    public TestScript(TimeSpan timeout)                  // Script timeout must be between 0 (infinite) and 32,767 seconds in length
Note: An ArgumentOutOfRangeException exception will be thrown if the specified TimeSpan is not between 0 and 32,767 seconds in duration.

Examples
    private readonly TestScript _testScript = new TestScript();
    private readonly TestScript _testScript = new TestScript(TimeSpan.FromMinutes(2));

AppendFile
AppendFile will append any required JavaScript file to the TestScript. Typically, this will be the JavaScript file under test, or common/shared JavaScript required by the file under test. AppendFile does not immediately validate that the file referenced is actually JavaScript; thus if a non-JavaScript file is referenced, a ScriptException will be thrown when you attempt to run a given unit test.

    public void AppendFile(String fileName);             // Renders a WSH script include element (i.e., <script language='JavaScript' src='{fileName}'></script>
Note: A FileNotFoundException exception will be thrown if the file does not exist.

Examples
    _testScript.AppendFile(@"..\..\..\Web\Scripts\common.js");
    _testScript.AppendFile(@"F:\SourceCode\JSTest\JSTest\Web\Scripts\eventDispatcher.js");

AppendBlock
AppendBlock will append any required JavaScript code block to the TestScript. Typically, this will be embedded JavaScript libraries or common/shared JavaScript setup required by the file under test. AppendFile does not immediately validate that the code referenced is actually JavaScript; thus if a non-JavaScript file is referenced, a ScriptException will be thrown when you attempt to run a given unit test.

    public void AppendBlock(String scriptBlock);         // Renders a WSH script element (i.e., <script language='JavaScript'>{scriptBlock}</script>
    public void AppendBlock(ScriptBlock scriptElement);  // Renders a WSH script element (i.e., <script language='JavaScript'>{scriptBlock}</script>

Examples
    _testScript.AppendBlock(new JsHamcrestLibrary());
    _testScript.AppendBlock(@"var dispatcher = new EventDispatcher();");
    _testScript.AppendBlock(String.Format("var x = {0}", JsonConverter.Serialize(new { id = 1, value = "one" }));
    _testScript.AppendBlock(new EmbeddedScriptBlock(typeof(SomeType).Assembly, "full.namespace.resource.name"));

Several commonly used JavaScript mock and assertion libraries have been embedded in JSTest for conveniance. Specifiaclly, the following five JavaScript libraries are included an may be referenced if desired:
Finally, for those not interested in using JsHamcrest to perform their assertions/validations, a very simple assertion library has also been embedded for ease of use: testScript.AppendBlock(new JsAssertLibrary());
RunTest
RunTest will invoke the specified JavaScript unit test with access to only those script blocks/includes appended to TestScript. Run test will return a JSON string containing the return value from the test block if specified.
    public String RunTest(String scriptBlock);           // Returns unparsed JSON from the unit test JavaScript block.
_Note: A ScriptException exception will be thrown if the JavaScript is invalid (i.e., undefined variable, bad syntax, etc), the script times out or if the script throws an exception.

Examples
    //No return value specified
    _testScript.RunTest(@"var mockPredicateAlternate = JsMockito.mockFunction();
                           
                          JsMockito.when(mockPredicateAlternate)(fakeEvent).thenThrow('MyException');
      
                          dispatcher.attachListener(mockHandler, mockPredicateAlternate);
                          dispatcher.processEvent(fakeEvent);

                          JsMockito.verify(mockPredicateAlternate)(fakeEvent);
                          JsMockito.verifyZeroInteractions(mockHandler);
                        ");

    //Return value specified
    var json = _testScript.RunTest(@"var mockPredicateAlternate = JsMockito.mockFunction();
                           
                                     JsMockito.when(mockPredicateAlternate)(fakeEvent).thenThrow('MyException');
      
                                     dispatcher.attachListener(mockHandler, mockPredicateAlternate);
                                     dispatcher.processEvent(fakeEvent);

                                     JsMockito.verify(mockPredicateAlternate)(fakeEvent);
                                     JsMockito.verifyZeroInteractions(mockHandler);

                                     return fakeEvent;
                                   ");


JsAssertLibrary (JavaScript assertions)

For those looking for simple assertions similar to those found in MSTest, NUnit or xUnit, JSTest includes a very simple assert object that may be used when appended to any given TestScript instance.

    assert.fail = function (message);
    assert.isTrue = function (expression, message);
    assert.isFalse = function (expression, message);
    assert.isNull = function (actual, message);
    assert.isNotNull = function (actual, message);
    assert.isUndefined = function (actual, message);
    assert.isNotUndefined = function (actual, message);
    assert.equal = function (expected, actual, message);
    assert.notEqual = function (notExpected, actual, message);
    assert.throws = function (expected, action, message);

Note: message is always an optional parameter.

Please referencce JsAssertLibraryTests.cs for usage examples.

Last edited Dec 22, 2012 at 6:53 PM by CBaxter, version 12

Comments

No comments yet.