Skip to content

D
doctrine-dbal
Switch branch/tag
Find file
Normal viewHistoryPermalink
group_test_documentation.html 12 KB
Newer Older
zYne's avatar
--no commit message
df2b2ef8
 
zYne committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>SimpleTest for PHP group test documentation</title>
<link rel="stylesheet" type="text/css" href="docs.css" title="Styles">
</head>
<body>
<div class="menu_back">
<div class="menu">
<h2>
<a href="index.html">SimpleTest</a>
</h2>
<ul>
<li>
<a href="overview.html">Overview</a>
</li>
<li>
<a href="unit_test_documentation.html">Unit tester</a>
</li>
<li>
<span class="chosen">Group tests</span>
</li>
<li>
<a href="server_stubs_documentation.html">Server stubs</a>
</li>
<li>
<a href="mock_objects_documentation.html">Mock objects</a>
</li>
<li>
<a href="partial_mocks_documentation.html">Partial mocks</a>
</li>
<li>
<a href="reporter_documentation.html">Reporting</a>
</li>
<li>
<a href="expectation_documentation.html">Expectations</a>
</li>
<li>
<a href="web_tester_documentation.html">Web tester</a>
</li>
<li>
<a href="form_testing_documentation.html">Testing forms</a>
</li>
<li>
<a href="authentication_documentation.html">Authentication</a>
</li>
<li>
<a href="browser_documentation.html">Scriptable browser</a>
</li>
</ul>
</div>
</div>
<h1>Group Test documentation</h1>
<div class="content">
        <p>
<a class="target" name="group">
<h2>Grouping tests</h2>
</a>
</p>
            <p>
                To run test cases as part of a group the test cases should really
                be placed in files without the runner code...
<pre>
<strong>&lt;?php
    require_once('../classes/io.php');

    class FileTester extends UnitTestCase {
        ...
    }

    class SocketTester extends UnitTestCase {
        ...
    }
?&gt;</strong>
</pre>
                As many cases as needed can appear in a single file.
                They should include any code they need, such as the library
                being tested, but none of the simple test libraries.
            </p>
            <p>
                If you have extended any test cases, you can include them
                as well.
<pre>
&lt;?php
    require_once('../classes/io.php');
<strong>
    class MyFileTestCase extends UnitTestCase {
        ...
    }
    SimpleTestOptions::ignore('MyFileTestCase');</strong>

    class FileTester extends MyFileTestCase {
        ...
    }

    class SocketTester extends UnitTestCase {
        ...
    }
?&gt;
</pre>
                The <span class="new_code">FileTester</span> class does
                not contain any actual tests, but is a base class for other
                test cases.
                For this reason we use the
                <span class="new_code">SimpleTestOptions::ignore()</span> directive
                to tell the upcoming group test to ignore it.
                This directive can appear anywhere in the file and works
                when a whole file of test cases is loaded (see below).
                We will call this sample <em>file_test.php</em>.
            </p>
            <p>
                Next we create a group test file, called say <em>group_test.php</em>.
                You will think of a better name I am sure.
                We will add the test file using a safe method...
<pre>
&lt;?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');<strong>
    require_once('file_test.php');

    $test = &amp;new GroupTest('All file tests');
    $test-&gt;addTestCase(new FileTestCase());
    $test-&gt;run(new HtmlReporter());</strong>
?&gt;
</pre>
                This instantiates the test case before the test suite is
                run.
                This could get a little expensive with a large number of test
                cases, so another method is provided that will only
                instantiate the class when it is needed...
<pre>
&lt;?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');
    require_once('file_test.php');

    $test = &amp;new GroupTest('All file tests');<strong>
    $test-&gt;addTestClass('FileTestCase');</strong>
    $test-&gt;run(new HtmlReporter());
?&gt;
</pre>
                The problem with this method is that for every test case
                that we add we will have
                to <span class="new_code">require_once()</span> the test code
                file and manually instantiate each and every test case.
                We can save a lot of typing with...
<pre>
&lt;?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');

    $test = &amp;new GroupTest('All file tests');<strong>
    $test-&gt;addTestFile('file_test.php');</strong>
    $test-&gt;run(new HtmlReporter());
?&amp;gt;
</pre>
                What happens here is that the <span class="new_code">GroupTest</span>
                class has done the <span class="new_code">require_once()</span>
                for us.
                It then checks to see if any new test case classes
                have been created by the new file and automatically adds
                them to the group test.
                Now all we have to do is add each new file.
            </p>
            <p>
                There are two things that could go wrong and which require care...
                <ol>
                    <li>
                        The file could already have been parsed by PHP and so no
                        new classes will have been added. You should make
                        sure that the test cases are only included in this file
                        and no others.
                    </li>
                    <li>
                        New test case extension classes that get included will be
                        placed in the group test and run also.
                        You will need to add a <span class="new_code">SimpleTestOptions::ignore()</span>
                        directive for these classes or make sure that they are included
                        before the <span class="new_code">GroupTest::addTestFile()</span>
                        line.
                    </li>
                </ol>
            </p>
        
        <p>
<a class="target" name="higher">
<h2>Higher groupings</h2>
</a>
</p>
            <p>
                The above method places all of the test cases into one large group.
                For larger projects though this may not be flexible enough; you
                may want to group the tests in all sorts of ways.
            </p>
            <p>
                To get a more flexible group test we can subclass
                <span class="new_code">GroupTest</span> and then instantiate it as needed...
<pre>
&lt;?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');
    <strong>
    class FileGroupTest extends GroupTest {
        function FileGroupTest() {
            $this-&gt;GroupTest('All file tests');
            $this-&gt;addTestFile('file_test.php');
        }
    }</strong>
?&gt;
</pre>
                This effectively names the test in the constructor and then
                adds our test cases and a single group below.
                Of course we can add more than one group at this point.
                We can now invoke the tests from a separate runner file...
<pre>
&lt;?php
    require_once('file_group_test.php');
    <strong>
    $test = &amp;new FileGroupTest();
    $test-&gt;run(new HtmlReporter());</strong>
?&gt;
</pre>
                ...or we can group them into even larger group tests...
<pre>
&lt;?php
    require_once('file_group_test.php');
    <strong>
    $test = &amp;new BigGroupTest('Big group');
    $test-&gt;addTestCase(new FileGroupTest());
    $test-&gt;addTestCase(...);
    $test-&gt;run(new HtmlReporter());</strong>
?&gt;
</pre>
                If we still wish to run the original group test and we
                don't want all of these little runner files, we can
                put the test runner code around guard bars when we create
                each group.
<pre>
&lt;?php
    class FileGroupTest extends GroupTest {
        function FileGroupTest() {
            $this-&gt;GroupTest('All file tests');
            $test-&gt;addTestFile('file_test.php');
        }
    }
    <strong>
    if (! defined('RUNNER')) {
        define('RUNNER', true);</strong>
        $test = &amp;new FileGroupTest();
        $test-&gt;run(new HtmlReporter());
    }
?&gt;
</pre>
                This approach requires the guard to be set when including
                the group test file, but this is still less hassle than
                lots of separate runner files.
                You include the same guard on the top level tests to make sure
                that <span class="new_code">run()</span> will run once only
                from the top level script that has been invoked.
<pre>
&lt;?php<strong>
    define('RUNNER', true);</strong>
    require_once('file_group_test.php');

    $test = &amp;new BigGroupTest('Big group');
    $test-&gt;addTestCase(new FileGroupTest());
    $test-&gt;addTestCase(...);
    $test-&gt;run(new HtmlReporter());
?&gt;
</pre>
                As with the normal test cases, a <span class="new_code">GroupTest</span> can
                be loaded with the <span class="new_code">GroupTest::addTestFile()</span> method.
<pre>
&lt;?php
    define('RUNNER', true);

    $test = &amp;new BigGroupTest('Big group');<strong>
    $test-&gt;addTestFile('file_group_test.php');
    $test-&gt;addTestFile(...);</strong>
    $test-&gt;run(new HtmlReporter());
?&gt;
</pre>
            </p>
        
        <p>
<a class="target" name="legacy">
<h2>Integrating legacy test cases</h2>
</a>
</p>
            <p>
                If you already have unit tests for your code or are extending external
                classes that have tests, it is unlikely that all of the test cases
                are in SimpleTest format.
                Fortunately it is possible to incorporate test cases from other
                unit testers directly into SimpleTest group tests.
            </p>
            <p>
                Say we have the following
                <a href="http://sourceforge.net/projects/phpunit">PhpUnit</a>
                test case in the file <em>config_test.php</em>...
<pre>
<strong>class ConfigFileTest extends TestCase {
    function ConfigFileTest() {
        $this-&gt;TestCase('Config file test');
    }
    
    function testContents() {
        $config = new ConfigFile('test.conf');
        $this-&gt;assertRegexp('/me/', $config-&gt;getValue('username'));
    }
}</strong>
</pre>
                The group test can recognise this as long as we include
                the appropriate adapter class before we add the test
                file...
<pre>
&lt;?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');<strong>
    require_once('simpletest/adapters/phpunit_test_case.php');</strong>

    $test = &amp;new GroupTest('All file tests');<strong>
    $test-&gt;addTestFile('config_test.php');</strong>
    $test-&gt;run(new HtmlReporter());
?&gt;
</pre>
                There are only two adapters, the other is for the
                <a href="http://pear.php.net/manual/en/package.php.phpunit.php">PEAR</a>
                1.0 unit tester...
<pre>
&lt;?php
    require_once('simpletest/unit_tester.php');
    require_once('simpletest/reporter.php');<strong>
    require_once('simpletest/adapters/pear_test_case.php');</strong>

    $test = &amp;new GroupTest('All file tests');<strong>
    $test-&gt;addTestFile('some_pear_test_cases.php');</strong>
    $test-&gt;run(new HtmlReporter());
?&gt;
</pre>
                The PEAR test cases can be freely mixed with SimpleTest
                ones even in the same test file,
                but you cannot use SimpleTest assertions in the legacy
                test case versions.
                This is done as a check that you are not accidently making
                your test cases completely dependent on SimpleTest.
                You may want to do a PEAR release of your library for example
                which would mean shipping it with valid PEAR::PhpUnit test
                cases.
            </p>
        
    </div>
<div class="copyright">
            Copyright<br>Marcus Baker, Jason Sweat, Perrick Penet 2004
        </div>
</body>
</html>