Nickolay - Test.Run-0.06

Documentation | Source

Name

Test.Run - Yet another JavaScript testing platform

SYNOPSIS

In your harness (index.html):

        Test.Run.Harness.Browser.Multi.my.configure({
            title : 'Module.Stub Test Suite',

            passThroughEx : true,

            preload : [
                '/jsan/Task/Joose/Core.js',
                "/jsan/JooseX/SimpleRequest.js",
                '/jsan/Task/JooseX/Namespace/Depended/Web.js',
                {
                    text : "JooseX.Namespace.Depended.Manager.my.INC = " + Ext.encode(INC)
                }
            ]
        })


        Test.Run.Harness.Browser.Multi.my.start(
            '010_sanity.t.js',
            '020_basics.t.js'
        )

In individual test file (e.g. 01_sanity.t.js):

        StartTest(function(t) {

            t.plan(1)

            var async0 = t.beginAsync()

            use('Module.Stub', function () {

                //=========================================
                t.diag('Sanity')

                t.ok(Module.Stub, "Module.Stub is here")

                t.endAsync(async0)
            })
        })

DESCRIPTION

Test.Run is a JavaScript testing tool, currently aimed mostly for testing modules running on browser platform.

This tool do not strictly implement any testing protocol, though in general, it follows the TAP principles.

DEMO

To give you a quick overview how your test suite will looks like:

Passing test suite: http://jsan.symbie.org/Joose3/mutability/t/

Test suite with bugs: http://jsan.symbie.org/test.run/demo/multi.html

GETTING STARTED

Below is the introductory tutorial, assuming testing on browser platform.

Test suite

All files of the test suite are placed under /t or /tests (or similar) directory of your distribution. You need to have a harness and a group of individual files there. Generally, you can organize it as you prefer, a common case for example is to have an additional lib: /t/lib with helper libraries.

Harness

Since we are on the browser platform, you need to create a "harness" file: index.html. Harness is some kind of dashboard, which concentrates the results from several individual test files.

Harness implementation is written using ExtJS framework, bridged to Joose. The simplest way to create it will be just to copy it from Module.Stub distribution.

Before starting the suite, harness should be configured: 

        Test.Run.Harness.Browser.Multi.my.configure({
            title : 'Module.Stub Test Suite',

            passThroughEx : true,

            preload : [
                '/jsan/Task/Joose/Core.js',
                "/jsan/JooseX/SimpleRequest.js",
                '/jsan/Task/JooseX/Namespace/Depended/Web.js',
                {
                    text : "JooseX.Namespace.Depended.Manager.my.INC = " + Ext.encode(INC)
                }
            ]
        })

In the example above, we set the title of the whole suite (title), then specified, which files needs to be preloaded before starting each individual test (preload).

For a complete reference of available configuration options please refer to Test.Run.Harness.Browser.Multi documentation.

After configuration we start the suite, specifying the list of testing files:

        Test.Run.Harness.Browser.Multi.my.start(
            '010_sanity.t.js',
            '020_another_test.t.js'
        )

Individual tests

Each individual test file will be run in separate and absolutely clean global scope (either iframe or popup window). The only symbol, embedded in that scope will be a StartTest function, with which you should wrap your testing code. Testing code, in turn, should be wrapped with function, which will receive an instance of Test.Run.Test.Browser

Actual testing is performed using the methods of that instance:

        StartTest(function(t) {

            t.plan(2)


            t.diag('Sanity')

            t.ok(1 == 1,    'Indeed #1')
            t.is(2 * 2, 4,  'Indeed #2')
        })

The first call on the instance should be plan. With this call you will specify the planned number of tests (assertions) in the file. This will guarantee to handle the situation of premature test ending.

Other calls should check various assertions about your code.

For a complete list of supported assertions refer to Test.Run.Test.Browser documentation.

TODO

  • Implement SKIP and TODO support
  • Implement more assertion checks (notably isDeeply)
  • Encapsulate run-cores ('in turn' and 'simultaneous')
  • Add support for SSJS-based harness
  • Add benchmarking capabilities

GETTING HELP

This extension is supported via github issues tracker: http://github.com/SamuraiJack/Test-Run/issues

For general Joose questions you can also visit #joose on irc.freenode.org or the forum at: http://joose.it/forum

SEE ALSO

Web page of this module: http://github.com/SamuraiJack/Test-Run/

General documentation for Joose: http://openjsan.org/go/?l=Joose

BUGS

All complex software has bugs lurking in it, and this module is no exception.

Please report any bugs through the web interface at http://github.com/SamuraiJack/Test-Run/issues

AUTHORS

Nickolay Platonov nplatonov@cpan.org

COPYRIGHT AND LICENSE

Copyright (c) 2009, Nickolay Platonov

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Neither the name of Nickolay Platonov nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

Class('Test.Run', {
    
    my : {
        
        have : {
            harness : null
        },
        
        
        methods : {
            
            configure : function (config) {
                Joose.O.copy(config, this)
            },

            
            start : function (testFunc, testClass, topScope) {
                (this.harness || window.parent.Test.Run.my.harness || window.opener.Test.Run.my.harness || Test.Run.Harness.Browser.Single.my).startTest(testFunc, testClass, topScope)
            }
            
        }
        
    }
    //eof my
})
//eof Test.Run


//starter, which also capture the top scope - it will be re-defined in Test.Run.Harness.Browser
StartTest = function (testFunc, testClass) {
    Test.Run.my.start(testFunc, testClass, this)
}

__EXCEPTION_CATCHER__ = function (func) { var ex; try { func() } catch (e) { ex = e; }; return ex; }