PageRenderTime 39ms CodeModel.GetById 12ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 1ms

/docs/source/en/overview.xml

https://github.com/francois2metz/simpletest
XML | 455 lines | 451 code | 3 blank | 1 comment | 0 complexity | 8d19e2beda58da4839e9801d38143ee2 MD5 | raw file
  1<?xml version="1.0"?>
  2<!-- $Id$ -->
  3<page title="Overview of SimpleTest" here="Overview">
  4    <long_title>
  5        Overview and feature list for the SimpleTest PHP unit tester and web tester
  6    </long_title>
  7    <content>
  8        <section name="summary" title="What is SimpleTest?">
  9            <p>
 10                The heart of SimpleTest is a testing framework built around
 11                test case classes.
 12                These are written as extensions of base test case classes,
 13                each extended with methods that actually contain test code.
 14                Each test method of a test case class is written to invoke
 15                various assertions that the developer expects to be true such as
 16                <code>assertEqual()</code>.
 17                If the expectation is correct, then a successful result is
 18                dispatched to the observing test reporter, but any failure
 19                or unexpected exception triggers an alert and a description
 20                of the mismatch.
 21                These test case declarations are transformed into executable
 22                test scripts by including a SimpleTest aurorun.php file.
 23            </p>
 24            <p>
 25                These documents apply to SimpleTest version 1.1, although we
 26                try hard to maintain compatibility between versions.
 27                If you get a test failure after an upgrade, check out the
 28                file &quot;HELP_MY_TESTS_DONT_WORK_ANYMORE&quot; in the
 29                simpletest directory to see if a feature you are using
 30                has since been deprecated and later removed.
 31            </p>
 32            <p>
 33                A <a local="unit_test_documentation">test case</a> looks like this...
 34<php><![CDATA[
 35<?php
 36require_once('simpletest/autorun.php');
 37
 38class <strong>CanAddUp</strong> extends UnitTestCase {<strong>
 39    function testWillCreateLogFileOnFirstMessage() {
 40        $this->assertEqual(1 + 1, 2);
 41    }</strong>
 42}
 43?>
 44]]></php>
 45                Tests are grouped into test cases, which are just
 46                PHP classes that extend <code>UnitTestCase</code>
 47                or <code>WebTestCase</code>.
 48                The tests themselves are just normal methods that start
 49                their name with the letters &quot;test&quot;.
 50                You can have as many test cases as you want in a test
 51                script and each test case can have as many test methods
 52                as it wants too.
 53            </p>
 54            <p>
 55                This test script is immediately runnable.
 56            </p>
 57            <p>
 58                When run on the command line you should see something like...
 59<pre class="shell">
 60adding_test.php
 61OK
 62Test cases run: 1/1, Passes: 1, Failures: 0, Exceptions: 0
 63</pre>
 64            </p>
 65            <p>
 66                If you place it on a web server and point your
 67                web browser at it...
 68                <div class="demo">
 69                    <h1>adding_test.php</h1>
 70                    <div style="padding: 8px; margin-top: 1em; background-color: green; color: white;">1/1 test cases complete.
 71                    <strong>6</strong> passes, <strong>0</strong> fails and <strong>0</strong> exceptions.</div>
 72                </div>
 73            </p>
 74            <p>
 75                Of course this is a silly example.
 76                A more realistic example might be...
 77<php><![CDATA[
 78<?php
 79require_once('simpletest/autorun.php');
 80require_once('log.php');
 81
 82class <strong>TestOfLogging</strong> extends UnitTestCase {
 83    function testWillCreateLogFileOnFirstMessage() {
 84        $log = new Log('my.log');
 85        $this->assertFalse(file_exists('my.log'));
 86        $log->message('Hello');
 87        $this->assertTrue(file_exists('my.log'));
 88    }</strong>
 89}
 90?>
 91]]></php>
 92            </p>
 93            <p>
 94                This tool is designed for the developer.
 95                The target audience of this tool is anyone developing a small
 96                to medium PHP application, including developers new to
 97                unit and web regression testing.
 98                The core principles are ease of use first, with extendibility and
 99                essential features.
100            </p>
101            <p>
102                Tests are written in the PHP language itself more or less
103                as the application itself is built.
104                The advantage of using PHP as the testing language is that
105                there are no new languages to learn, testing can start straight away,
106                and the developer can test any part of the code.
107                Basically, all parts that can be accessed by the application code can also be
108                accessed by the test code when they are in the same programming language.
109            </p>
110            <p>
111                The simplest type of test case is the
112                <a local="unit_tester_documentation">UnitTestCase</a>.
113                This class of test case includes standard tests for equality,
114                references and pattern matching.
115                All these test the typical expectations of what you would
116                expect the result of a function or method to be.
117                This is by far the most common type of test in the daily
118                routine of development, making up about 95% of test cases.
119            </p>
120            <p>
121                The top level task of a web application though is not to
122                produce correct output from its methods and objects, but
123                to generate web pages.
124                The <a local="web_tester_documentation">WebTestCase</a> class tests web
125                pages.
126                It simulates a web browser requesting a page, complete with
127                cookies, proxies, secure connections, authentication, forms, frames and most
128                navigation elements.
129                With this type of test case, the developer can assert that
130                information is present in the page and that forms and
131                sessions are handled correctly.
132            </p>
133            <p>
134                A <a local="web_tester_documentation">WebTestCase</a> looks like this...
135<php><![CDATA[
136<?php
137require_once('simpletest/autorun.php');
138require_once('simpletest/web_tester.php');
139
140class <strong>MySiteTest</strong> extends WebTestCase {
141    <strong>
142    function testHomePageHasContactDetails() {
143        $this->get('http://www.my-site.com/index.php');
144        $this->assertTitle('My Home Page');
145        $this->clickLink('Contact');
146        $this->assertTitle('Contact me');
147        $this->assertText('/Email me at/');
148    }</strong>
149}
150?>
151]]></php>
152            </p>
153        </section>
154        <section name="features" title="Feature list">
155            <p>
156                The following is a very rough outline of past and future features
157                and their expected point of release.
158                I am afraid it is liable to change without warning, as meeting the
159                milestones rather depends on time available.
160            </p>
161            <p>
162                Green stuff has been coded, but not necessarily released yet.
163                If you have a pressing need for a green but unreleased feature
164                then you should check-out the code from Sourceforge SVN directly.
165                <table><thead>
166                    <tr><th>Feature</th><th>Description</th><th>Release</th></tr>
167                    </thead><tbody><tr>
168                        <td>Unit test case</td>
169                        <td>Core test case class and assertions</td>
170                        <td style="color: green;">1.0</td>
171                    </tr>
172                    <tr>
173                        <td>Html display</td>
174                        <td>Simplest possible display</td>
175                        <td style="color: green;">1.0</td>
176                    </tr>
177                    <tr>
178                        <td>Autoloading of test cases</td>
179                        <td>
180                            Reading a file with test cases and loading them into a
181                            group test automatically
182                        </td>
183                        <td style="color: green;">1.0</td>
184                    </tr>
185                    <tr>
186                        <td>Mock objects</td>
187                        <td>
188                            Objects capable of simulating other objects removing
189                            test dependencies
190                        </td>
191                        <td style="color: green;">1.0</td>
192                    </tr>
193                    <tr>
194                        <td>Web test case</td>
195                        <td>Allows link following and title tag matching</td>
196                        <td style="color: green;">1.0</td>
197                    </tr>
198                    <tr>
199                        <td>Partial mocks</td>
200                        <td>
201                            Mocking parts of a class for testing less than a class
202                            or for complex simulations
203                        </td>
204                        <td style="color: green;">1.0</td>
205                    </tr>
206                    <tr>
207                        <td>Web cookie handling</td>
208                        <td>Correct handling of cookies when fetching pages</td>
209                        <td style="color: green;">1.0</td>
210                    </tr>
211                    <tr>
212                        <td>Following redirects</td>
213                        <td>Page fetching automatically follows 300 redirects</td>
214                        <td style="color: green;">1.0</td>
215                    </tr>
216                    <tr>
217                        <td>Form parsing</td>
218                        <td>Ability to submit simple forms and read default form values</td>
219                        <td style="color: green;">1.0</td>
220                    </tr>
221                    <tr>
222                        <td>Command line interface</td>
223                        <td>Test display without the need of a web browser</td>
224                        <td style="color: green;">1.0</td>
225                    </tr>
226                    <tr>
227                        <td>Exposure of expectation classes</td>
228                        <td>Can create precise tests with mocks as well as test cases</td>
229                        <td style="color: green;">1.0</td>
230                    </tr>
231                    <tr>
232                        <td>XML output and parsing</td>
233                        <td>
234                            Allows multi host testing and the integration of acceptance
235                            testing extensions
236                        </td>
237                        <td style="color: green;">1.0</td>
238                    </tr>
239                    <tr>
240                        <td>Browser component</td>
241                        <td>
242                            Exposure of lower level web browser interface for more
243                            detailed test cases
244                        </td>
245                        <td style="color: green;">1.0</td>
246                    </tr>
247                    <tr>
248                        <td>HTTP authentication</td>
249                        <td>
250                            Fetching protected web pages with basic authentication
251                            only
252                        </td>
253                        <td style="color: green;">1.0</td>
254                    </tr>
255                    <tr>
256                        <td>SSL support</td>
257                        <td>Can connect to https: pages</td>
258                        <td style="color: green;">1.0</td>
259                    </tr>
260                    <tr>
261                        <td>Proxy support</td>
262                        <td>Can connect via. common proxies</td>
263                        <td style="color: green;">1.0</td>
264                    </tr>
265                    <tr>
266                        <td>Frames support</td>
267                        <td>Handling of frames in web test cases</td>
268                        <td style="color: green;">1.0</td>
269                    </tr>
270                    <tr>
271                        <td>File upload testing</td>
272                        <td>Can simulate the input type file tag</td>
273                        <td style="color: green;">1.0.1</td>
274                    </tr>
275                    <tr>
276                        <td>Mocking interfaces</td>
277                        <td>
278                            Can generate mock objects to interfaces as well as classes
279                            and class interfaces are carried for type hints
280                        </td>
281                        <td style="color: green;">1.0.1</td>
282                    </tr>
283                    <tr>
284                        <td>Testing exceptions</td>
285                        <td>Similar to testing PHP errors</td>
286                        <td style="color: green;">1.0.1</td>
287                    </tr>
288                    <tr>
289                        <td>HTML label support</td>
290                        <td>Can access all controls using the visual label</td>
291                        <td style="color: green;">1.0.1</td>
292                    </tr>
293                    <tr>
294                        <td>Base tag support</td>
295                        <td>Respects page base tag when clicking</td>
296                        <td style="color: green;">1.0.1</td>
297                    </tr>
298                    <tr>
299                        <td>PHP 5 E_STRICT compliant</td>
300                        <td>PHP 5 only version that works with the E_STRICT error level</td>
301                        <td style="color: green;">1.1</td>
302                    </tr>
303                    <tr>
304                        <td>Alternate HTML parsers</td>
305                        <td>Can detect compiled parsers for performance improvements</td>
306                        <td style="color: green;">1.1</td>
307                    </tr>
308                    <tr>
309                        <td>REST support</td>
310                        <td>Support for REST verbs as put(), delete(), etc.</td>
311                        <td style="color: green;">1.1</td>
312                    </tr>
313                    <tr>
314                        <td>BDD style fixtures</td>
315                        <td>Can import fixtures using a mixin like given() method</td>
316                        <td style="color: red;">1.5</td>
317                    </tr>
318                    <tr>
319                        <td>Plug-in architecture</td>
320                        <td>Automatic import of extensions including command line options</td>
321                        <td style="color: red;">1.5</td>
322                    </tr>
323                    <tr>
324                        <td>Reporting machinery enhancements</td>
325                        <td>Improved message passing for better cooperation with IDEs</td>
326                        <td style="color: red;">1.5</td>
327                    </tr>
328                    <tr>
329                        <td>Fluent mock interface</td>
330                        <td>More flexible and concise mock objects</td>
331                        <td style="color: red;">1.6</td>
332                    </tr>
333                    <tr>
334                        <td>Localisation</td>
335                        <td>Messages abstracted and code generated as well as UTF support</td>
336                        <td style="color: red;">1.6</td>
337                    </tr>
338                    <tr>
339                        <td>CSS selectors</td>
340                        <td>HTML content can be examined using CSS selectors</td>
341                        <td style="color: red;">1.7</td>
342                    </tr>
343                    <tr>
344                        <td>HTML table assertions</td>
345                        <td>Can match HTML or table elements to expectations</td>
346                        <td style="color: red;">1.7</td>
347                    </tr>
348                    <tr>
349                        <td>Unified acceptance testing model</td>
350                        <td>Content searchable through selectors combined with expectations</td>
351                        <td style="color: red;">1.7</td>
352                    </tr>
353                    <tr>
354                        <td>DatabaseTestCase</td>
355                        <td>SQL selectors and DB drivers</td>
356                        <td style="color: red;">1.7</td>
357                    </tr>
358                    <tr>
359                        <td>IFrame support</td>
360                        <td>Reads IFrame content that can be refreshed</td>
361                        <td style="color: red;">1.8</td>
362                    </tr>
363                    <tr>
364                        <td>Integrated Selenium support</td>
365                        <td>Easy to use built in Selenium driver and tutorial or similar browser automation</td>
366                        <td style="color: red;">1.9</td>
367                    </tr>
368                    <tr>
369                        <td>Code coverage</td>
370                        <td>Reports using the bundled tool when using XDebug</td>
371                        <td style="color: red;">1.9</td>
372                    </tr>
373                    <tr>
374                        <td>Deprecation of old methods</td>
375                        <td>Simpler interface for SimpleTest2</td>
376                        <td style="color: red;">2.0</td>
377                    </tr>
378                    <tr>
379                        <td>Javascript suport</td>
380                        <td>Use of PECL module to add Javascript to the native browser</td>
381                        <td style="color: red;">3.0</td>
382                    </tr>
383                </tbody></table>
384                PHP 5 migration is complete, which means that only PHP 5.0.3+
385                will be supported in SimpleTest version 1.1+.
386                Earlier versions of SimpleTest are compatible with PHP 4.2 up to
387                PHP 5 (non E_STRICT).
388            </p>
389        </section>
390    </content>
391    <internal>
392        <link>
393            <a href="#summary">Quick summary</a>
394            of the SimpleTest tool for PHP.
395        </link>
396        <link>
397            <a href="#features">List of features</a>,
398            both current ones and those planned.
399        </link>
400    </internal>
401    <external>
402        <link>
403            <a local="unit_test_documentation">Documentation for SimpleTest</a>.
404        </link>
405        <link>
406            <a href="http://www.lastcraft.com/first_test_tutorial.php">How to write PHP test cases</a>
407            is a fairly advanced tutorial.
408        </link>
409        <link>
410            <a href="http://simpletest.org/api/">SimpleTest API</a> from phpdoc.
411        </link>
412    </external>
413    <meta>
414        <keywords>
415            software development tools,
416            php programming,
417            programming php,
418            software development tools,
419            Tools for extreme programming,
420            free php scripts,
421            links of testing tools,
422            php testing resources,
423            mock objects,
424            junit,
425            jwebunit,
426            htmlunit,
427            itc,
428            php testing links,
429            unit test advice and documentation,
430            extreme programming in php
431        </keywords>
432    </meta>
433    <refsynopsisdiv>
434        <authorgroup>
435            <author>
436                Marcus Baker
437                <authorblurb>
438                    <para>Primary Developer</para><para>{@link mailto:marcus@lastcraft.com marcus@lastcraft.com}</para>
439                </authorblurb>
440            </author>
441            <author>
442                Perrick Pennet
443                <authorblurb>
444                    <para>General manager</para><para>{@link mailto:perrick@noparking.net perrick@noparking.net}</para>
445                </authorblurb>
446            </author>
447            <author>
448                Jason Sweat
449                <authorblurb>
450                    <para>Documentation</para><para>{@link mailto:jsweat_php@yahoo.com jsweat_php@yahoo.com}</para>
451                </authorblurb>
452            </author>
453        </authorgroup>
454    </refsynopsisdiv>
455</page>