osteele / lztestkit

BDD for OpenLaszlo.

This URL has Read+Write access

lztestkit / README
raw normal view history
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 1 = LZTestKit
d13314f6 » osteele 2007-12-28 +doc files 2
3 This package extends lzunit with behavioral testing, asynchronous
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 4 test support, test case selection, and automated test sequencing.
5
6 * <b>Test case selection</b> runs a single test case within a test
7 applet, without modifying the sources. (You supply the name of the
8 test case as a query parameter in the application URL.) It allows
9 you to use your test applet as your debugging scaffolding, without
10 running a lot of code that you aren't interested in.
11
12 * <b>Automated test sequencing</b> runs all the test applets in a
13 directory, in series, in a single browser window, stopping if one of
14 them has an error. It allows you to run all of a package's test
15 cases from the browser by visiting a single url, instead of
16 navigating to each url in turn.
17
18 * <b>Behavioral testing</b> implements mocks, stubs, and expectations.
19 It allows you to *test* one class, while *stubbing* the classes that
20 it depends on. You can even verify that the tested class makes
21 functions thatyou expect it to. This is a loose port of rspec to
4473686a » osteele 2007-12-28 update the readme 22 OpenLaszlo.
d13314f6 » osteele 2007-12-28 +doc files 23
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 24 * <b>Asynchronous test support</b> allows you to write a test case
25 that is only considered complete when the callback functions or
26 delegates that it defines return. If a test case creates a callback
27 function, the test case is only complete when the callback function
28 returns. (Except if the callback function creates a callback
29 function, etc.)
d13314f6 » osteele 2007-12-28 +doc files 30
31 == Requirements
32
4473686a » osteele 2007-12-28 update the readme 33 This package requires OpenLaszlo 3.4.0 or 4.0.6. (Other versions
b757dc20 » osteele 2007-12-28 example for test-selection 34 might work, but aren't tested.)
35
e228a1ca » osteele 2007-12-28 generate index.html 36 == Installation
37
38 * Download the latest version from {download-location}.
39
40 * Unpack it into your OpenLaszlo webapp directory; for example, at
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 41 <tt>${OPENLASZLO_HOME}/Server/lps-3.4.0/lztestkit</tt>.
e228a1ca » osteele 2007-12-28 generate index.html 42
6edd4d44 » osteele 2007-12-31 update docs; add credits file 43 * Visit e.g. http://127.0.0.1:8080/openlaszlo-4.0.6/lztestkit/examples
44 and http://127.0.0.1:8080/openlaszlo-4.0.6/lztestkit/test. (The
45 first part of the path will be different if you've got a different
46 version of OpenLaszlo, or if you've installed the servlet instead of
47 the server). You should be able to click on the examples and tests
48 in order to run them.
e228a1ca » osteele 2007-12-28 generate index.html 49
50 == Features
51
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 52 === Test case selection
b757dc20 » osteele 2007-12-28 example for test-selection 53
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 54 If a test application is compiled with support for test case selection, you
55 can invoke it with a <tt>testCase=<em>{testCaseName}</em></tt> query parameter
56 to run only the test case named <em>{testCaseName}</em>.
b757dc20 » osteele 2007-12-28 example for test-selection 57
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 58 Include <tt>lzunit-extensions.js</tt> in your application (or include
59 <tt>library.lzx</tt>, which includes this). Then, include the
60 testCase={testCaseName} query parameter in the URL that you use to
61 open the application, where {testCaseName} is the name of the test
62 case. Only this test case will execute.
b757dc20 » osteele 2007-12-28 example for test-selection 63
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 64 See the example in <tt>examples/test-selection.lzx</tt>.
d13314f6 » osteele 2007-12-28 +doc files 65
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 66 === Automated test sequencing
d13314f6 » osteele 2007-12-28 +doc files 67
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 68 Copy <tt>test/autorun/index.jsp</tt> into your test directory to run
69 all the test applications in that directory within a single browser
70 window, without user interaction.
71
72 Copy <tt>test/autorun/index.jsp</tt> into your test directory, and
73 update the includes at the top of the file to reflect the paths to the
74 lztestkit <tt>src</tt> and <tt>lib</tt> subdirectories. By default,
75 this file will run files in its directory that match /test-*.lzx/;
76 this is a configuration parameter that it should be obvious how to
77 change.
78
79 Each test cases should include <tt>autorun-lz.js</tt> via <script
80 src="autorun-lz.js"/>. If you have a <tt>library.lzx</tt> file with
81 test scaffolding, you can place that directive there.
82
83 ==== Support files
84 <tt>autorun-lz.js</tt>:: implements the OpenLaszlo side of automated execution
85 <tt>autorun-browser.js</tt>:: implements browser support
86 <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
87 <tt>jquery-1.2.1.min.js</tt>:: is the jQuery library. I didn't write this! but the browser support file needs it
88 <tt>swfobject.js</tt>:: is the swfobject library. I didn't write this! but the browser support file needs it
d13314f6 » osteele 2007-12-28 +doc files 89
90
e228a1ca » osteele 2007-12-28 generate index.html 91 === Behavioral testing
3f521072 » osteele 2007-12-28 +test cases for autorun 92
93 TODO
94
4473686a » osteele 2007-12-28 update the readme 95 This lets you write things like this in a test case:
96
97 myMockObject = Mock.Create(MyClass);
98 myMockObject.mock.expects.aMethod(1, 'arg', {name:2});
99 // call a fn that invokes myMockObject.aMethod(1, 'arg', {name:2})
100 myMockObject.mock.verify();
101
102 myMockObject.stub('aMethod', 'arg1', 'arg2', Function)
103 .by.calling(1);
104 // call a fn that invokes myMockObject.aMethod('arg1', 'arg2', function(n) {...})
105 // and expects the funarg to be called back with n=1
106
3f521072 » osteele 2007-12-28 +test cases for autorun 107 calling(anObject, 'methodName', 'arg1')
108 .should.call(otherObject, 'method', 'some', 'arguments')
109 .and.send(anObject, 'onchange', 'data')
110 .and.returnWith(1)
111
112 constructing('MyClass', 'initarg')
113 .should.call(otherObject, 'method', 'some', 'arguments')
114
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 115 ==== Implementation
3f521072 » osteele 2007-12-28 +test cases for autorun 116
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 117 <tt>lzmock.js</tt>:: TODO
118 <tt>lzspec.js</tt>:: TODO
119 <tt>lzunit-extensions.js</tt>:: adds <tt>assertNotEquals</tt>, <tt>assert[Not]Contains</tt>, and <tt>assertFasterThan</tt> methods to <tt>TestCase</tt>
120 <tt>jsspec.js</tt>:: js-level support for lzspec (without OpenLaszlo dependencies)
121 <tt>hopkit.js</tt>:: support file for jsspec and lzmock
3f521072 » osteele 2007-12-28 +test cases for autorun 122
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 123 === Asynchronous test support
3f521072 » osteele 2007-12-28 +test cases for autorun 124
4473686a » osteele 2007-12-28 update the readme 125 TODO
126
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 127 This features allows lzunit to run asynchronous tests, which are not
128 complete until a delegate or callback has been called. A typical
129 usage pattern is the following test, which asserts that setTimeout
130 delays at least the requested amount of time:
131
132 <method name="testSetTimeout" args="c">
133 var interval = 1000,
134 startTime = new Date;
135 // c(function(){...}) is equivalent to function(){...}
136 // except that it re-enters the dynamic bindings of the
137 // test case.
138 setTimeout(c(function() {
139 var endTime = new Date;
140 assertTrue(endTime - startTime >= interval);
141 }), interval);
142 </method>
143
397d41b9 » osteele 2007-12-31 +examples 144 For now, see <tt>examples/test-lzunit-async.lzx</tt>. The new methods are
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 145 also copiously documented in <tt>src/lzunit-async.lzx</tt>.
3f521072 » osteele 2007-12-28 +test cases for autorun 146
4473686a » osteele 2007-12-28 update the readme 147 == Support Files
3f521072 » osteele 2007-12-28 +test cases for autorun 148
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 149 The browser support for autorun relies on jQuery and swfobject. I've
150 included versions of these in the <tt>src</tt> directory.
d13314f6 » osteele 2007-12-28 +doc files 151
d9448eb2 » osteele 2007-12-28 update docs; restore autoru... 152 The behavioral testing files use hopkit.js to define chains.
153 <tt>hopkit</tt> isn't otherwise ready for general release; and it's
154 not necessary to use this file directly.
d13314f6 » osteele 2007-12-28 +doc files 155
156 == License
157
158 LzTestKit is copyright (c) 2007 Oliver Steele. It is open-source
159 software, and may be redistributed under the terms of the MIT
160 license. The text of this licence is included in the LzTestKit
161 distribution.