Nickolay - Test.Run-0.10

Name

Test.Run - Yet another JavaScript testing platform, allowing you to write cross-platform (browser/NodeJS) tests

SYNOPSIS

In your harness (index.js):

        var Harness

        if (typeof process != 'undefined' && process.pid) {
            require('Task/Test/Run/NodeJSBundle')

            Harness = Test.Run.Harness.NodeJS
        } else
            Harness = Test.Run.Harness.Browser.ExtJS

        var INC = [ '../lib', '/jsan/index.html' ]


        Harness.configure({
            title : 'Some.Cool.Module Test Suite',

            transparentEx   : true,

            preload : [
                'jsan:Task.Joose.Core',
                {
                    text : "some_setup(); SOME_PARAM = 'some_value';"
                }
            ]
        })


        Harness.start(
            '/doc/s/sa/samuraijack/Test/Run/010/lib/Test/010_sanity.t.js',
            '/doc/s/sa/samuraijack/Test/Run/010/lib/Test/020_basics.t.js'
        )

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

        StartTest(function(t) {

            var async0 = t.beginAsync()

            use('Some.Cool.Module', function () {

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

                t.ok(Some.Cool.Module, "Some.Cool.Module is here")

                t.endAsync(async0)

                t.done()
            })
        })

DESCRIPTION

Test.Run is a JavaScript testing tool, aimed for testing cross-platform (browser/NodeJS) modules.

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:

GETTING STARTED

Below is the introductory tutorial.

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 support the browser platform, we need a harness file, to manage the individual test files. Harness is some kind of dashboard, which set up the environment for each test and concentrates the results.

The simplest way to create a harness it will be just to copy it from some distribution, which use Test.Run, for example from this one

Before starting the suite, we detect the platform:

        var Harness

        if (typeof process != 'undefined' && process.pid) {
            require('Task/Test/Run/NodeJSBundle')

            Harness = Test.Run.Harness.NodeJS
        } else 
            Harness = Test.Run.Harness.Browser.ExtJS

Then we configure the test suite:

        var INC = [ '../lib', '/jsan/index.html' ]


        Harness.configure({
            title : 'JooseX.CPS Test Suite',

            transparentEx   : true,

            preload : Joose.is_NodeJS ? [
                'Task.Joose.CPS.NodeJSTest',
                {
                    text : "JooseX.Namespace.Depended.Manager.my.INC = " + JSON.stringify(INC)
                }

            ] : [
                'Task.JooseX.CPS.WebTest',
                {
                    text : "JooseX.Namespace.Depended.Manager.my.INC = " + Ext.encode(Harness.absolutizeINC(INC))
                }
            ]
        })

In the example above, we set the title of the whole suite (title option), then specified, which files needs to be pre-loaded before starting each individual test (preload option). Note that preload option is different for each platform.

For the complete list of available configuration options please refer to Test.Run.Harness documentation.

After configuration, we start the suite, specifying the list of individual test files. These files are assumed to be in the same directory as the harness file.

        Harness.start(
            '/doc/s/sa/samuraijack/Test/Run/010/lib/Test/010_sanity.t.js',
            '/doc/s/sa/samuraijack/Test/Run/010/lib/Test/020_another_test.t.js'
        )

Note, that for browser platform, you'll also need an html wrapper for the harness (index.html).

Individual tests

Each individual test file will be run in separate and absolutely clean global scope. 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

Actual testing is performed using the methods of that instance:

        StartTest(function(t) {

            t.diag('Sanity')

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

            t.done()
        })

The very last call on the instance should be done. With this call you will specify that all the planned tests have been ran. This will guarantee to handle the situation of premature test ending. Alternatively, you can set up the testing plan:

        StartTest(function(t) {

            t.plan(2)

            t.diag('Sanity')

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

Other calls should check various assertions about your code.

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

TODO

Implement more assertion checks (notably isDeeply)
Add support for stand-alone SSJS-based harness, which will run each test in own process
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

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

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 : {
        
        methods : {
            
        }
        
    }
})