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
var isNode = typeof process != 'undefined' && process.pid
if (isNode) {
require('Task/Test/Run/NodeJSBundle')
Harness = Test.Run.Harness.NodeJS
} else
Harness = Test.Run.Harness.Browser.ExtJS
var INC = (isNode ? require.paths : []).concat('../lib', '/jsan')
Harness.configure({
title : 'Sample.Dist Test Suite',
preload : [
"jsan:Task.Joose.Core",
"jsan:Task.JooseX.Namespace.Depended.Auto",
{
text : "use.paths = " + Harness.prepareINC(INC)
}
]
})
Harness.start(
'010_sanity.t.js',
'020_basic.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()
})
})
If links in this document aren't work correctly, try to open it from here
INSTALLATION & SETUP
Installation from npm:
> [sudo] npm install test-run
When using this module for testing in browsers you'll need to have the local web-server and access the files of your suite through it. Please also refer to the 3.1 and 3.2 items of Joose installation notes
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:
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
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 the synopsys above. Lets examine it.
Before starting the suite, we detect the platform:
var Harness
var isNode = typeof process != 'undefined' && process.pid
if (isNode) {
require('Task/Test/Run/NodeJSBundle')
Harness = Test.Run.Harness.NodeJS
} else
Harness = Test.Run.Harness.Browser.ExtJS
Then we configure the test suite with the call to Harness.configure:
var INC = (isNode ? require.paths : []).concat('../lib', '/jsan')
Harness.configure({
title : 'Sample.Dist Test Suite',
preload : [
"jsan:Task.Joose.Core",
"jsan:Task.JooseX.Namespace.Depended.Auto",
{
text : "use.paths = " + Harness.prepareINC(INC)
}
]
})
Each test will be ran in completely separate and clean global scope and preload option specifies with what code it will be filled prior starting the test.
We've chose to preload the 'Task.Joose.Core' module from the cross-platform library and auto-configurable bundle of the JooseX.Namespace.Depended.
Note, that its possible to just directly specify the code to execute in the scope of the test (object with 'text' property).
Tests may have individual values for preload option.
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:
Harness.start(
'010_sanity.t.js',
'020_another_test.t.js',
'/extra/010_some_extra_test.t.js'
)
To launch the harness in NodeJS, just run the harness file (usually index.js):
> node index.js
To launch the harness on browser platform, first create a small html wrapper index.html, like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<link rel="stylesheet" type="text/css" href="/jsan/Task/ExtJS/resources/css/ext-all.css">
<link rel="stylesheet" type="text/css" href="/jsan/Test/Run/static/css/all.css">
<script type="text/javascript" src="/jsan/Task/Test/Run/WebBundle.js"></script>
<script type="text/javascript" src="index.js"></script>
</head>
<body>
</body>
</html>
Then put the test suite in some web-directory and point your browser to the wrapper (using your local web-server). You should see the harness application like in demo links.
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, to which you should pass the function with tests.
That function 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.
Further reading
Test.Run.Harness documentation.
Test.Run.Test documentation.
TODO
- 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
You can also ask questions at IRC channel : #joose
Or the mailing list: http://groups.google.com/group/joose-js
SEE ALSO
Web page of this module: http://github.com/SamuraiJack/Test-Run/
General documentation for Joose: http://joose.github.com/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) 2010, 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.