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

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

Added SimpleTest? test framework

File size: 14.6 KB
Line 
1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
4<title>SimpleTest for PHP test suites</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                <a href="unit_test_documentation.html">Unit tester</a>
14                |
15                <span class="chosen">Group tests</span>
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>Test suite documentation</h1>
34        This page...
35        <ul>
36<li>
37            Different ways to <a href="#group">group tests</a> together.
38        </li>
39<li>
40            Combining group tests into <a href="#higher">larger groups</a>.
41        </li>
42<li>
43            Integrating <a href="#legacy">legacy test cases</a> from other
44            types of PHPUnit.
45        </li>
46</ul>
47<div class="content">
48        <p><a class="target" name="group"><h2>Grouping tests into suites</h2></a></p>
49            <p>
50                To run test cases as part of a group, the test cases should really
51                be placed in files without the runner code...
52<pre>
53<strong>&lt;?php
54    require_once('../classes/io.php');
55
56    class FileTester extends UnitTestCase {
57        ...
58    }
59
60    class SocketTester extends UnitTestCase {
61        ...
62    }
63?&gt;</strong>
64</pre>
65                As many cases as needed can appear in a single file.
66                They should include any code they need, such as the library
67                being tested, but none of the simple test libraries.
68            </p>
69            <p>
70                If you have extended any test cases, you can include them
71                as well. In PHP 4...
72<pre>
73&lt;?php
74    require_once('../classes/io.php');
75<strong>
76    class MyFileTestCase extends UnitTestCase {
77        ...
78    }
79    SimpleTest::ignore('MyFileTestCase');</strong>
80
81    class FileTester extends MyFileTestCase { ... }
82
83    class SocketTester extends UnitTestCase { ... }
84?&gt;
85</pre>
86                The <span class="new_code">FileTester</span> class does
87                not contain any actual tests, but is a base class for other
88                test cases.
89                For this reason we use the
90                <span class="new_code">SimpleTestOptions::ignore()</span> directive
91                to tell the upcoming group test to ignore it.
92                This directive can appear anywhere in the file and works
93                when a whole file of test cases is loaded (see below).
94            </p>
95            <p>
96                If you are using PHP 5, you do not need this special directive at all.
97                Simply mark any test cases that should not be run as abstract...
98<pre>
99<strong>abstract</strong> class MyFileTestCase extends UnitTestCase {
100    ...
101}
102
103class FileTester extends MyFileTestCase { ... }
104
105class SocketTester extends UnitTestCase { ... }
106</pre>
107            </p>
108            <p>
109                We will call this sample <em>file_test.php</em>.
110                Next we create a group test file, called say <em>my_group_test.php</em>.
111                You will think of a better name I am sure.
112            </p>
113            <p>
114                We will add the test file using a safe method...
115<pre>
116&lt;?php
117    require_once('simpletest/unit_tester.php');
118    require_once('simpletest/reporter.php');<strong>
119    require_once('file_test.php');
120
121    $test = &amp;new TestSuite('All file tests');
122    $test-&gt;addTestCase(new FileTestCase());
123    $test-&gt;run(new HtmlReporter());</strong>
124?&gt;
125</pre>
126                This instantiates the test case before the test suite is
127                run.
128                This could get a little expensive with a large number of test
129                cases, and can be surprising behaviour.
130            </p>
131            <p>
132                The main problem is that for every test case
133                that we add we will have
134                to <span class="new_code">require_once()</span> the test code
135                file and manually instantiate each and every test case.
136            </p>
137            <p>
138                We can save a lot of typing with...
139<pre>
140&lt;?php
141    require_once('simpletest/unit_tester.php');
142    require_once('simpletest/reporter.php');
143
144    $test = &amp;new TestSuite('All file tests');<strong>
145    $test-&gt;addTestFile('file_test.php');</strong>
146    $test-&gt;run(new HtmlReporter());
147?&amp;gt;
148</pre>
149                What happens here is that the <span class="new_code">TestSuite</span>
150                class has done the <span class="new_code">require_once()</span>
151                for us.
152                It then checks to see if any new test case classes
153                have been created by the new file and automatically adds
154                them to the group test.
155                Now all we have to do is add each new file.
156            </p>
157            <p>
158                No only that, but you can guarantee that the constructor is run
159                just before the first test method and, in PHP 5, the destructor
160                is run just after the last test method.
161            </p>
162            <p>
163                There are two things that could go wrong and which require care...
164                <ol>
165                    <li>
166                        The file could already have been parsed by PHP, and so no
167                        new classes will have been added. You should make
168                        sure that the test cases are only included in this file
169                        and no others (Note : with the new <cite>autorun</cite>
170                        functionnality, this problem has now been solved).
171                    </li>
172                    <li>
173                        New test case extension classes that get included will be
174                        placed in the group test and run also.
175                        You will need to add a <span class="new_code">SimpleTestOptions::ignore()</span>
176                        directive for these classes, or make sure that they are included
177                        before the <span class="new_code">TestSuite::addTestFile()</span>
178                        line, or make sure that they are abstract classes.
179                    </li>
180                </ol>
181            </p>
182       
183        <p><a class="target" name="higher"><h2>Composite suites</h2></a></p>
184            <p>
185                The above method places all of the test cases into one large group.
186                For larger projects though this may not be flexible enough; you
187                may want to group the tests in all sorts of ways.
188            </p>
189            <p>
190                To get a more flexible group test we can subclass
191                <span class="new_code">TestSuite</span> and then instantiate it as needed...
192<pre>
193&lt;?php
194    require_once('simpletest/unit_tester.php');
195    require_once('simpletest/reporter.php');
196    <strong>
197    class FileTestSuite extends TestSuite {
198        function FileTestSuite() {
199            $this-&gt;TestSuite('All file tests');
200            $this-&gt;addTestFile('file_test.php');
201        }
202    }</strong>
203?&gt;
204</pre>
205                This effectively names the test in the constructor and then
206                adds our test cases and a single group below.
207                Of course we can add more than one group at this point.
208                We can now invoke the tests from a separate runner file...
209<pre>
210&lt;?php
211    require_once('file_test_suite.php');
212    <strong>
213    $test = &amp;new FileTestSuite();
214    $test-&gt;run(new HtmlReporter());</strong>
215?&gt;
216</pre>
217                ...or we can group them into even larger group tests.
218                We can even mix groups and test cases freely as long as
219                we are careful about double includes...
220<pre>
221&lt;?php
222    <strong>
223    $test = &amp;new BigTestSuite('Big group');
224    $test-&gt;addTestFile('file_test_suite.php');
225    $test-&gt;addTestFile('some_test_case.php');</strong>
226    $test-&gt;run(new HtmlReporter());
227?&gt;
228</pre>
229                In the event of a double include, ony the first instance
230                of the test case will be run.
231            </p>
232            <p>
233                If we still wish to run the original group test, and we
234                don't want all of these little runner files, we can
235                put the test runner code around guard bars when we create
236                each group.
237<pre>
238&lt;?php
239    class FileTestSuite extends TestSuite {
240        function FileTestSuite() {
241            $this-&gt;TestSuite('All file tests');
242            $test-&gt;addTestFile('file_test.php');
243        }
244    }
245    <strong>
246    if (! defined('RUNNER')) {
247        define('RUNNER', true);</strong>
248        $test = &amp;new FileTestSuite();
249        $test-&gt;run(new HtmlReporter());
250    }
251?&gt;
252</pre>
253                This approach requires the guard to be set when including
254                the group test file, but this is still less hassle than
255                lots of separate runner files.
256                You include the same guard on the top level tests to make sure
257                that <span class="new_code">run()</span> will run once only
258                from the top level script that has been invoked.
259<pre>
260&lt;?php<strong>
261    define('RUNNER', true);</strong>
262    require_once('file_test_suite.php');
263
264    $test = &amp;new BigTestSuite('Big group');
265    $test-&gt;addTestCase(new FileTestSuite());
266    $test-&gt;addTestCase(...);
267    $test-&gt;run(new HtmlReporter());
268?&gt;
269</pre>
270                As with the normal test cases, a <span class="new_code">TestSuite</span> can
271                be loaded with the <span class="new_code">TestSuite::addTestFile()</span> method.
272<pre>
273&lt;?php
274    define('RUNNER', true);
275
276    $test = &amp;new BigTestSuite('Big group');<strong>
277    $test-&gt;addTestFile('file_test_suite.php');
278    $test-&gt;addTestFile(...);</strong>
279    $test-&gt;run(new HtmlReporter());
280?&gt;
281</pre>
282            </p>
283       
284        <p><a class="target" name="legacy"><h2>Integrating legacy test cases</h2></a></p>
285            <p>
286                If you already have unit tests for your code or are extending external
287                classes that have tests, it is unlikely that all of the test cases
288                are in SimpleTest format.
289                Fortunately it is possible to incorporate test cases from other
290                unit testers directly into SimpleTest group tests.
291            </p>
292            <p>
293                Say we have the following
294                <a href="http://sourceforge.net/projects/phpunit">PhpUnit</a>
295                test case in the file <em>config_test.php</em>...
296<pre>
297<strong>class ConfigFileTest extends TestCase {
298    function ConfigFileTest() {
299        $this-&gt;TestCase('Config file test');
300    }
301   
302    function testContents() {
303        $config = new ConfigFile('test.conf');
304        $this-&gt;assertRegexp('/me/', $config-&gt;getValue('username'));
305    }
306}</strong>
307</pre>
308                The group test can recognise this as long as we include
309                the appropriate adapter class before we add the test
310                file...
311<pre>
312&lt;?php
313    require_once('simpletest/unit_tester.php');
314    require_once('simpletest/reporter.php');<strong>
315    require_once('simpletest/adapters/phpunit_test_case.php');</strong>
316
317    $test = &amp;new TestSuite('All file tests');<strong>
318    $test-&gt;addTestFile('config_test.php');</strong>
319    $test-&gt;run(new HtmlReporter());
320?&gt;
321</pre>
322                There are only two adapters, the other is for the
323                <a href="http://pear.php.net/manual/en/package.php.phpunit.php">PEAR</a>
324                1.0 unit tester...
325<pre>
326&lt;?php
327    require_once('simpletest/unit_tester.php');
328    require_once('simpletest/reporter.php');<strong>
329    require_once('simpletest/adapters/pear_test_case.php');</strong>
330
331    $test = &amp;new TestSuite('All file tests');<strong>
332    $test-&gt;addTestFile('some_pear_test_cases.php');</strong>
333    $test-&gt;run(new HtmlReporter());
334?&gt;
335</pre>
336                The PEAR test cases can be freely mixed with SimpleTest
337                ones even in the same test file,
338                but you cannot use SimpleTest assertions in the legacy
339                test case versions.
340                This is done as a check that you are not accidently making
341                your test cases completely dependent on SimpleTest.
342                You may want to do a PEAR release of your library for example,
343                which would mean shipping it with valid PEAR::PhpUnit test
344                cases.
345            </p>
346       
347    </div>
348        References and related information...
349        <ul>
350<li>
351            SimpleTest project page on <a href="http://sourceforge.net/projects/simpletest/">SourceForge</a>.
352        </li>
353<li>
354            SimpleTest download page on <a href="http://www.lastcraft.com/simple_test.php">LastCraft</a>.
355        </li>
356</ul>
357<div class="menu_back"><div class="menu">
358<a href="index.html">SimpleTest</a>
359                |
360                <a href="overview.html">Overview</a>
361                |
362                <a href="unit_test_documentation.html">Unit tester</a>
363                |
364                <span class="chosen">Group tests</span>
365                |
366                <a href="mock_objects_documentation.html">Mock objects</a>
367                |
368                <a href="partial_mocks_documentation.html">Partial mocks</a>
369                |
370                <a href="reporter_documentation.html">Reporting</a>
371                |
372                <a href="expectation_documentation.html">Expectations</a>
373                |
374                <a href="web_tester_documentation.html">Web tester</a>
375                |
376                <a href="form_testing_documentation.html">Testing forms</a>
377                |
378                <a href="authentication_documentation.html">Authentication</a>
379                |
380                <a href="browser_documentation.html">Scriptable browser</a>
381</div></div>
382<div class="copyright">
383            Copyright<br>Marcus Baker 2006
384        </div>
385</body>
386</html>
Note: See TracBrowser for help on using the repository browser.