Docs For Class DocTest

Class DocTest

Description

Tests PHP code by executing usage examples in the documentation.

If you have a file called example.php like this below, and execute it, the DocTest class will really execute add(20, 22) and compare the output to 42. It will output, that this test passes.

   <?php
     // This file is example.php
     /**
      * Adds two numbers.
      * Usage example:
      * <code>
      *  echo add(20, 22); /// 42
      * </code>
      */
     function add($a, $b) {
         return $a + $b;
     }

     if (__FILE__ == realpath($_SERVER['SCRIPT_FILENAME'])) {
         require_once 'DocTest.php';
         DocTest::testfile();
     }
   ?>

You can call the test also from another file like this:

$test = new DocTest('example.php');
$test->run();
var_dump($test->failed()); /// bool(false)
echo $test->toString();
// will output:
/// DocTest of file example.php
/// 1 passed and 0 failed.
/// Test passed.

There are some more methods to examine the result of the test. See the list below.

The used syntax is compatible to the documentation syntax of PhpDocumentor.

The praxis of doc tests is very common under python programmers. Python has a build in module for doc tests. Due it's no part of the PHP language (yet) there are several PHP classes in the web following the same principle. For example:

Sometimes you are not able to test your application only with doc tests. In some cases a more complex testing framework is usefull. I recommend PhpUnit, which has a similar functionality to JUnit for Java.

This class is part of the uBook Project.

author: Maikel Linke (contact formular)
version: 2010-09-11

Located in /DocTest.php (line 88)

Method Summary

static void testfile ([ $file = null], [ $verbose = null])

DocTest __construct (string $testCandidate)

bool failed ()

string getExpected ()

int getLineNumber ()

string getResult ()

int numOfPassed ()

void run ([bool $verbose = false])

string toString ()

Methods

static method testfile (line 367)

access: public

static void testfile ([ $file = null], [ $verbose = null])

$file
$verbose

Constructor __construct (line 110)

Creates a test for $testCandidate.

access: public

DocTest __construct (string $testCandidate)

string $testCandidate: PHP file with documentation

failed (line 126)

Determines, if the test failed or not.

$test = new DocTest('example.php');
var_dump($test->failed()); /// NULL
$test->run();
var_dump($test->failed()); /// bool(false)

return: true, if the test failed
access: public

bool failed ()

getExpected (line 178)

Returns the last expected output of the tested code.

$badTest = new DocTest('example_bad.php');
$badTest->run();
var_dump($badTest->getExpected()); /// string(2) "42"

return: expected result
access: public

string getExpected ()

getLineNumber (line 165)

Returns the last line number before an assertion failed or the test terminated successfully.

$badTest = new DocTest('example_bad.php');
$badTest->run();
var_dump($badTest->getLineNumber()); /// int(9)

return: number of the last code line
access: public

int getLineNumber ()

getResult (line 191)

Returns the real output of the tested code.

$badTest = new DocTest('example_bad.php');
$badTest->run();
var_dump($badTest->getResult()); /// string(3) "440"

return: result of the tested code
access: public

string getResult ()

numOfPassed (line 151)

Returns the number of passed assertion before the test failed or terminated successfully.

$test = new DocTest('example.php');
$test->run();
var_dump($test->numOfPassed()); /// int(1)
$badTest = new DocTest('example_bad.php');
$badTest->run();
var_dump($badTest->numOfPassed()); /// int(0)

return: number of passed assertions
access: public

int numOfPassed ()

run (line 243)

Runs all code examples until one fails.

access: public

void run ([bool $verbose = false])

bool $verbose: switches verbosity on, if true

toString (line 217)

Creates a human readable string with the result of the test.

$badTest = new DocTest('example_bad.php');
$badTest->run();
echo $badTest->toString();
// will output:
/// **********************************************************************
/// DocTest of file example_bad.php, line 9
/// Failed example:
/// $c = add_bad(20, 22);
/// echo $c;
/// // will not result in:
///
/// Expected: 42
/// But got: 440
/// 0 passed and 1 failed.
/// *** Test failed. ***
/// **********************************************************************

return: pretty representation of the test result
access: public

string toString ()

Documentation generated on Tue, 25 Oct 2011 19:51:47 +0200 by phpDocumentor 1.4.3