= LZTestKit
This package extends lzunit with behavioral testing, asynchronous
test support, test case selection, and automated test sequencing.
* <b>Test case selection</b> runs a single test case within a test
applet, without modifying the sources. (You supply the name of the
test case as a query parameter in the application URL.) It allows
you to use your test applet as your debugging scaffolding, without
running a lot of code that you aren't interested in.
* <b>Automated test sequencing</b> runs all the test applets in a
directory, in series, in a single browser window, stopping if one of
them has an error. It allows you to run all of a package's test
cases from the browser by visiting a single url, instead of
navigating to each url in turn.
* <b>Behavioral testing</b> implements mocks, stubs, and expectations.
It allows you to *test* one class, while *stubbing* the classes that
it depends on. You can even verify that the tested class makes
functions thatyou expect it to. This is a loose port of rspec to
OpenLaszlo.
* <b>Asynchronous test support</b> allows you to write a test case
that is only considered complete when the callback functions or
delegates that it defines return. If a test case creates a callback
function, the test case is only complete when the callback function
returns. (Except if the callback function creates a callback
function, etc.)
== Requirements
This package requires OpenLaszlo 3.4.0 or 4.0.6. (Other versions
might work, but aren't tested.)
== Installation
* Download the latest version from {download-location}.
* Unpack it into your OpenLaszlo webapp directory; for example, at
<tt>${OPENLASZLO_HOME}/Server/lps-3.4.0/lztestkit</tt>.
* Visit e.g. http://127.0.0.1:8080/openlaszlo-4.0.6/lztestkit/examples
and http://127.0.0.1:8080/openlaszlo-4.0.6/lztestkit/test. (The
first part of the path will be different if you've got a different
version of OpenLaszlo, or if you've installed the servlet instead of
the server). You should be able to click on the examples and tests
in order to run them.
== Features
=== Test case selection
If a test application is compiled with support for test case selection, you
can invoke it with a <tt>testCase=<em>{testCaseName}</em></tt> query parameter
to run only the test case named <em>{testCaseName}</em>.
Include <tt>lzunit-extensions.js</tt> in your application (or include
<tt>library.lzx</tt>, which includes this). Then, include the
testCase={testCaseName} query parameter in the URL that you use to
open the application, where {testCaseName} is the name of the test
case. Only this test case will execute.
See the example in <tt>examples/test-selection.lzx</tt>.
=== Automated test sequencing
Copy <tt>test/autorun/index.jsp</tt> into your test directory to run
all the test applications in that directory within a single browser
window, without user interaction.
Copy <tt>test/autorun/index.jsp</tt> into your test directory, and
update the includes at the top of the file to reflect the paths to the
lztestkit <tt>src</tt> and <tt>lib</tt> subdirectories. By default,
this file will run files in its directory that match /test-*.lzx/;
this is a configuration parameter that it should be obvious how to
change.
Each test cases should include <tt>autorun-lz.js</tt> via <script
src="autorun-lz.js"/>. If you have a <tt>library.lzx</tt> file with
test scaffolding, you can place that directive there.
==== Support files
<tt>autorun-lz.js</tt>:: implements the OpenLaszlo side of automated execution
<tt>autorun-browser.js</tt>:: implements browser support
<tt>autorun-include.jsp</tt>:: is a JSP include that embeds the files in the current directory into the generated HTML for the index page
<tt>jquery-1.2.1.min.js</tt>:: is the jQuery library. I didn't write this! but the browser support file needs it
<tt>swfobject.js</tt>:: is the swfobject library. I didn't write this! but the browser support file needs it
=== Behavioral testing
TODO
This lets you write things like this in a test case:
myMockObject = Mock.Create(MyClass);
myMockObject.mock.expects.aMethod(1, 'arg', {name:2});
// call a fn that invokes myMockObject.aMethod(1, 'arg', {name:2})
myMockObject.mock.verify();
myMockObject.stub('aMethod', 'arg1', 'arg2', Function)
.by.calling(1);
// call a fn that invokes myMockObject.aMethod('arg1', 'arg2', function(n) {...})
// and expects the funarg to be called back with n=1
calling(anObject, 'methodName', 'arg1')
.should.call(otherObject, 'method', 'some', 'arguments')
.and.send(anObject, 'onchange', 'data')
.and.returnWith(1)
constructing('MyClass', 'initarg')
.should.call(otherObject, 'method', 'some', 'arguments')
==== Implementation
<tt>lzmock.js</tt>:: TODO
<tt>lzspec.js</tt>:: TODO
<tt>lzunit-extensions.js</tt>:: adds <tt>assertNotEquals</tt>, <tt>assert[Not]Contains</tt>, and <tt>assertFasterThan</tt> methods to <tt>TestCase</tt>
<tt>jsspec.js</tt>:: js-level support for lzspec (without OpenLaszlo dependencies)
<tt>hopkit.js</tt>:: support file for jsspec and lzmock
=== Asynchronous test support
TODO
This features allows lzunit to run asynchronous tests, which are not
complete until a delegate or callback has been called. A typical
usage pattern is the following test, which asserts that setTimeout
delays at least the requested amount of time:
<method name="testSetTimeout" args="c">
var interval = 1000,
startTime = new Date;
// c(function(){...}) is equivalent to function(){...}
// except that it re-enters the dynamic bindings of the
// test case.
setTimeout(c(function() {
var endTime = new Date;
assertTrue(endTime - startTime >= interval);
}), interval);
</method>
For now, see <tt>examples/test-lzunit-async.lzx</tt>. The new methods are
also copiously documented in <tt>src/lzunit-async.lzx</tt>.
== Support Files
The browser support for autorun relies on jQuery and swfobject. I've
included versions of these in the <tt>src</tt> directory.
The behavioral testing files use hopkit.js to define chains.
<tt>hopkit</tt> isn't otherwise ready for general release; and it's
not necessary to use this file directly.
== License
LzTestKit is copyright (c) 2007 Oliver Steele. It is open-source
software, and may be redistributed under the terms of the MIT
license. The text of this licence is included in the LzTestKit
distribution.
) is private.
