source: trunk/server/www/vendors/simpletest/docs/en/unit_test_documentation.html @ 6

Last change on this file since 6 was 6, checked in by sander, 11 years ago

Added SimpleTest? test framework

File size: 16.2 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
4<title>SimpleTest for PHP regression test documentation</title>
5<link rel="stylesheet" type="text/css" href="docs.css" title="Styles">
6</head>
7<body>
8<div class="menu_back"><div class="menu">
9<a href="index.html">SimpleTest</a>
10                |
11                <a href="overview.html">Overview</a>
12                |
13                <span class="chosen">Unit tester</span>
14                |
15                <a href="group_test_documentation.html">Group tests</a>
16                |
17                <a href="mock_objects_documentation.html">Mock objects</a>
18                |
19                <a href="partial_mocks_documentation.html">Partial mocks</a>
20                |
21                <a href="reporter_documentation.html">Reporting</a>
22                |
23                <a href="expectation_documentation.html">Expectations</a>
24                |
25                <a href="web_tester_documentation.html">Web tester</a>
26                |
27                <a href="form_testing_documentation.html">Testing forms</a>
28                |
29                <a href="authentication_documentation.html">Authentication</a>
30                |
31                <a href="browser_documentation.html">Scriptable browser</a>
32</div></div>
33<h1>PHP Unit Test documentation</h1>
34        This page...
35        <ul>
36<li>
37            <a href="#unit">Unit test cases</a> and basic assertions.
38        </li>
39<li>
40            <a href="#extending_unit">Extending test cases</a> to
41            customise them for your own project.
42        </li>
43<li>
44            <a href="#running_unit">Running a single case</a> as
45            a single script.
46        </li>
47</ul>
48<div class="content">
49        <p><a class="target" name="unit"><h2>Unit test cases</h2></a></p>
50            <p>
51                The core system is a regression testing framework built around
52                test cases.
53                A sample test case looks like this...
54<pre>
55<strong>class FileTestCase extends UnitTestCase {
56}</strong>
57</pre>
58                Actual tests are added as methods in the test case whose names
59                by default start with the string "test" and
60                when the test case is invoked all such methods are run in
61                the order that PHP introspection finds them.
62                As many test methods can be added as needed.
63            </p>
64            <p>
65                For example...
66<pre>
67require_once('simpletest/autorun.php');
68require_once('../classes/writer.php');
69
70class FileTestCase extends UnitTestCase {
71    function FileTestCase() {
72        $this-&gt;UnitTestCase('File test');
73    }<strong>
74   
75    function setUp() {
76        @unlink('../temp/test.txt');
77    }
78   
79    function tearDown() {
80        @unlink('../temp/test.txt');
81    }
82   
83    function testCreation() {
84        $writer = &amp;new FileWriter('../temp/test.txt');
85        $writer-&gt;write('Hello');
86        $this-&gt;assertTrue(file_exists('../temp/test.txt'), 'File created');
87    }</strong>
88}
89</pre>
90                The constructor is optional and usually omitted.
91                Without a name, the class name is taken as the name of the test case.
92            </p>
93            <p>
94                Our only test method at the moment is <span class="new_code">testCreation()</span>
95                where we check that a file has been created by our
96                <span class="new_code">Writer</span> object.
97                We could have put the <span class="new_code">unlink()</span>
98                code into this method as well, but by placing it in
99                <span class="new_code">setUp()</span> and
100                <span class="new_code">tearDown()</span> we can use it with
101                other test methods that we add.
102            </p>
103            <p>
104                The <span class="new_code">setUp()</span> method is run
105                just before each and every test method.
106                <span class="new_code">tearDown()</span> is run just after
107                each and every test method.
108            </p>
109            <p>
110                You can place some test case set up into the constructor to
111                be run once for all the methods in the test case, but
112                you risk test inteference that way.
113                This way is slightly slower, but it is safer.
114                Note that if you come from a JUnit background this will not
115                be the behaviour you are used to.
116                JUnit surprisingly reinstantiates the test case for each test
117                method to prevent such interference.
118                SimpleTest requires the end user to use <span class="new_code">setUp()</span>, but
119                supplies additional hooks for library writers.
120            </p>
121            <p>
122                The means of reporting test results (see below) are by a
123                visiting display class
124                that is notified by various <span class="new_code">assert...()</span>
125                methods.
126                Here is the full list for the <span class="new_code">UnitTestCase</span>
127                class, the default for SimpleTest...
128                <table><tbody>
129                    <tr>
130<td><span class="new_code">assertTrue($x)</span></td>
131<td>Fail if $x is false</td>
132</tr>
133                    <tr>
134<td><span class="new_code">assertFalse($x)</span></td>
135<td>Fail if $x is true</td>
136</tr>
137                    <tr>
138<td><span class="new_code">assertNull($x)</span></td>
139<td>Fail if $x is set</td>
140</tr>
141                    <tr>
142<td><span class="new_code">assertNotNull($x)</span></td>
143<td>Fail if $x not set</td>
144</tr>
145                    <tr>
146<td><span class="new_code">assertIsA($x, $t)</span></td>
147<td>Fail if $x is not the class or type $t</td>
148</tr>
149                    <tr>
150<td><span class="new_code">assertNotA($x, $t)</span></td>
151<td>Fail if $x is of the class or type $t</td>
152</tr>
153                    <tr>
154<td><span class="new_code">assertEqual($x, $y)</span></td>
155<td>Fail if $x == $y is false</td>
156</tr>
157                    <tr>
158<td><span class="new_code">assertNotEqual($x, $y)</span></td>
159<td>Fail if $x == $y is true</td>
160</tr>
161                    <tr>
162<td><span class="new_code">assertWithinMargin($x, $y, $m)</span></td>
163<td>Fail if abs($x - $y) &lt; $m is false</td>
164</tr>
165                    <tr>
166<td><span class="new_code">assertOutsideMargin($x, $y, $m)</span></td>
167<td>Fail if abs($x - $y) &lt; $m is true</td>
168</tr>
169                    <tr>
170<td><span class="new_code">assertIdentical($x, $y)</span></td>
171<td>Fail if $x == $y is false or a type mismatch</td>
172</tr>
173                    <tr>
174<td><span class="new_code">assertNotIdentical($x, $y)</span></td>
175<td>Fail if $x == $y is true and types match</td>
176</tr>
177                    <tr>
178<td><span class="new_code">assertReference($x, $y)</span></td>
179<td>Fail unless $x and $y are the same variable</td>
180</tr>
181                    <tr>
182<td><span class="new_code">assertClone($x, $y)</span></td>
183<td>Fail unless $x and $y are identical copies</td>
184</tr>
185                    <tr>
186<td><span class="new_code">assertPattern($p, $x)</span></td>
187<td>Fail unless the regex $p matches $x</td>
188</tr>
189                    <tr>
190<td><span class="new_code">assertNoPattern($p, $x)</span></td>
191<td>Fail if the regex $p matches $x</td>
192</tr>
193                    <tr>
194<td><span class="new_code">expectError($x)</span></td>
195<td>Swallows any upcoming matching error</td>
196</tr>
197                    <tr>
198<td><span class="new_code">assert($e)</span></td>
199<td>Fail on failed <a href="expectation_documentation.html">expectation</a> object $e</td>
200</tr>
201                </tbody></table>
202                All assertion methods can take an optional description as a
203                last parameter.
204                This is to label the displayed result with.
205                If omitted a default message is sent instead, which is usually
206                sufficient.
207                This default message can still be embedded in your own message
208                if you include "%s" within the string.
209                All the assertions return true on a pass or false on failure.
210            </p>
211            <p>
212                Some examples...
213<pre>
214$variable = null;
215<strong>$this-&gt;assertNull($variable, 'Should be cleared');</strong>
216</pre>
217                ...will pass and normally show no message.
218                If you have
219                <a href="http://www.lastcraft.com/display_subclass_tutorial.php">set up the tester to display passes</a>
220                as well then the message will be displayed as is.
221<pre>
222<strong>$this-&gt;assertIdentical(0, false, 'Zero is not false [%s]');</strong>
223</pre>
224                This will fail as it performs a type
225                check, as well as a comparison, between the two values.
226                The "%s" part is replaced by the default
227                error message that would have been shown if we had not
228                supplied our own.
229<pre>
230$a = 1;
231$b = $a;
232<strong>$this-&gt;assertReference($a, $b);</strong>
233</pre>
234                Will fail as the variable <span class="new_code">$a</span> is a copy of <span class="new_code">$b</span>.
235<pre>
236<strong>$this-&gt;assertPattern('/hello/i', 'Hello world');</strong>
237</pre>
238                This will pass as using a case insensitive match the string
239                <span class="new_code">hello</span> is contained in <span class="new_code">Hello world</span>.
240<pre>
241<strong>$this-&gt;expectError();</strong>
242trigger_error('Catastrophe');
243</pre>
244                Here the check catches the "Catastrophe"
245                message without checking the text and passes.
246                This removes the error from the queue.
247<pre>
248<strong>$this-&gt;expectError('Catastrophe');</strong>
249trigger_error('Catastrophe');
250</pre>
251                The next error check tests not only the existence of the error,
252                but also the text which, here matches so another pass.
253                If any unchecked errors are left at the end of a test method then
254                an exception will be reported in the test.
255            </p>
256            <p>
257                Note that SimpleTest cannot catch compile time PHP errors.
258            </p>
259            <p>
260                The test cases also have some convenience methods for debugging
261                code or extending the suite...
262                <table><tbody>
263                    <tr>
264<td><span class="new_code">setUp()</span></td>
265<td>Runs this before each test method</td>
266</tr>
267                    <tr>
268<td><span class="new_code">tearDown()</span></td>
269<td>Runs this after each test method</td>
270</tr>
271                    <tr>
272<td><span class="new_code">pass()</span></td>
273<td>Sends a test pass</td>
274</tr>
275                    <tr>
276<td><span class="new_code">fail()</span></td>
277<td>Sends a test failure</td>
278</tr>
279                    <tr>
280<td><span class="new_code">error()</span></td>
281<td>Sends an exception event</td>
282</tr>
283                    <tr>
284<td><span class="new_code">signal($type, $payload)</span></td>
285<td>Sends a user defined message to the test reporter</td>
286</tr>
287                    <tr>
288<td><span class="new_code">dump($var)</span></td>
289<td>Does a formatted <span class="new_code">print_r()</span> for quick and dirty debugging</td>
290</tr>
291                </tbody></table>
292            </p>
293       
294        <p><a class="target" name="extending_unit"><h2>Extending test cases</h2></a></p>
295            <p>
296                Of course additional test methods can be added to create
297                specific types of test case, so as to extend framework...
298<pre>
299require_once('simpletest/autorun.php');
300<strong>
301class FileTester extends UnitTestCase {
302    function FileTester($name = false) {
303        $this-&gt;UnitTestCase($name);
304    }
305   
306    function assertFileExists($filename, $message = '%s') {
307        $this-&gt;assertTrue(
308                file_exists($filename),
309                sprintf($message, 'File [$filename] existence check'));
310    }</strong>
311}
312</pre>
313                Here the SimpleTest library is held in a folder called
314                <em>simpletest</em> that is local.
315                Substitute your own path for this.
316            </p>
317            <p>
318                To prevent this test case being run accidently, it is
319                advisable to mark it as <span class="new_code">abstract</span>.
320            </p>
321            <p>
322                Alternatively you could add a
323                <span class="new_code">SimpleTestOptions::ignore('FileTester');</span>
324                directive in your code.
325            </p>
326            <p>
327                This new case can be now be inherited just like
328                a normal test case...
329<pre>
330class FileTestCase extends <strong>FileTester</strong> {
331   
332    function setUp() {
333        @unlink('../temp/test.txt');
334    }
335   
336    function tearDown() {
337        @unlink('../temp/test.txt');
338    }
339   
340    function testCreation() {
341        $writer = &amp;new FileWriter('../temp/test.txt');
342        $writer-&gt;write('Hello');<strong>
343        $this-&gt;assertFileExists('../temp/test.txt');</strong>
344    }
345}
346</pre>
347            </p>
348            <p>
349                If you want a test case that does not have all of the
350                <span class="new_code">UnitTestCase</span> assertions,
351                only your own and a few basics,
352                you need to extend the <span class="new_code">SimpleTestCase</span>
353                class instead.
354                It is found in <em>simple_test.php</em> rather than
355                <em>unit_tester.php</em>.
356                See <a href="group_test_documentation.html">later</a> if you
357                want to incorporate other unit tester's
358                test cases in your test suites.
359            </p>
360       
361        <p><a class="target" name="running_unit"><h2>Running a single test case</h2></a></p>
362            <p>
363                You won't often run single test cases except when bashing
364                away at a module that is having difficulty, and you don't
365                want to upset the main test suite.
366                With <em>autorun</em> no particular scaffolding is needed,
367                just launch your particular test file and you're ready to go.
368            </p>
369            <p>
370                You can even decide which reporter (for example,
371                <span class="new_code">TextReporter</span> or <span class="new_code">HtmlReporter</span>)
372                you prefer for a specific file when launched on its own...
373<pre>
374&lt;?php
375require_once('simpletest/autorun.php');<strong>
376SimpleTest :: prefer(new TextReporter());</strong>
377require_once('../classes/writer.php');
378
379class FileTestCase extends UnitTestCase {
380    ...
381}
382?&gt;
383</pre>
384                This script will run as is, but of course will output zero passes
385                and zero failures until test methods are added.
386            </p>
387       
388    </div>
389        References and related information...
390        <ul>
391<li>
392            SimpleTest project page on <a href="http://sourceforge.net/projects/simpletest/">SourceForge</a>.
393        </li>
394<li>
395            SimpleTest download page on <a href="http://www.lastcraft.com/simple_test.php">LastCraft</a>.
396        </li>
397<li>
398            <a href="http://simpletest.org/api/">Full API for SimpleTest</a>
399            from the PHPDoc.
400        </li>
401</ul>
402<div class="menu_back"><div class="menu">
403<a href="index.html">SimpleTest</a>
404                |
405                <a href="overview.html">Overview</a>
406                |
407                <span class="chosen">Unit tester</span>
408                |
409                <a href="group_test_documentation.html">Group tests</a>
410                |
411                <a href="mock_objects_documentation.html">Mock objects</a>
412                |
413                <a href="partial_mocks_documentation.html">Partial mocks</a>
414                |
415                <a href="reporter_documentation.html">Reporting</a>
416                |
417                <a href="expectation_documentation.html">Expectations</a>
418                |
419                <a href="web_tester_documentation.html">Web tester</a>
420                |
421                <a href="form_testing_documentation.html">Testing forms</a>
422                |
423                <a href="authentication_documentation.html">Authentication</a>
424                |
425                <a href="browser_documentation.html">Scriptable browser</a>
426</div></div>
427<div class="copyright">
428            Copyright<br>Marcus Baker 2006
429        </div>
430</body>
431</html>
Note: See TracBrowser for help on using the repository browser.