1<?php
2/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
3
4/**
5 * PHP Version 4
6 *
7 * Copyright (c) 2002-2005, Sebastian Bergmann <sb@sebastian-bergmann.de>.
8 * All rights reserved.
9 *
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
12 * are met:
13 *
14 *   * Redistributions of source code must retain the above copyright
15 *     notice, this list of conditions and the following disclaimer.
16 *
17 *   * Redistributions in binary form must reproduce the above copyright
18 *     notice, this list of conditions and the following disclaimer in
19 *     the documentation and/or other materials provided with the
20 *     distribution.
21 *
22 *   * Neither the name of Sebastian Bergmann nor the names of his
23 *     contributors may be used to endorse or promote products derived
24 *     from this software without specific prior written permission.
25 *
26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
27 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
28 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
29 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
30 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
31 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
32 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
33 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
34 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRIC
35 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
36 * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
37 * POSSIBILITY OF SUCH DAMAGE.
38 *
39 * @category   Testing
40 * @package    PHPUnit
41 * @author     Sebastian Bergmann <sb@sebastian-bergmann.de>
42 * @copyright  2002-2005 Sebastian Bergmann <sb@sebastian-bergmann.de>
43 * @license    http://www.opensource.org/licenses/bsd-license.php  BSD License
44 * @version    CVS: $Id: TestCase.php,v 1.21 2005/11/10 09:47:14 sebastian Exp $
45 * @link       http://pear.php.net/package/PHPUnit
46 * @since      File available since Release 1.0.0
47 */
48
49require_once 'PHPUnit/Assert.php';
50require_once 'PHPUnit/TestResult.php';
51
52/**
53 * A TestCase defines the fixture to run multiple tests.
54 *
55 * To define a TestCase
56 *
57 *   1) Implement a subclass of PHPUnit_TestCase.
58 *   2) Define instance variables that store the state of the fixture.
59 *   3) Initialize the fixture state by overriding setUp().
60 *   4) Clean-up after a test by overriding tearDown().
61 *
62 * Each test runs in its own fixture so there can be no side effects
63 * among test runs.
64 *
65 * Here is an example:
66 *
67 * <code>
68 * <?php
69 * class MathTest extends PHPUnit_TestCase {
70 *     var $fValue1;
71 *     var $fValue2;
72 *
73 *     function MathTest($name) {
74 *         $this->PHPUnit_TestCase($name);
75 *     }
76 *
77 *     function setUp() {
78 *         $this->fValue1 = 2;
79 *         $this->fValue2 = 3;
80 *     }
81 * }
82 * ?>
83 * </code>
84 *
85 * For each test implement a method which interacts with the fixture.
86 * Verify the expected results with assertions specified by calling
87 * assert with a boolean.
88 *
89 * <code>
90 * <?php
91 * function testPass() {
92 *     $this->assertTrue($this->fValue1 + $this->fValue2 == 5);
93 * }
94 * ?>
95 * </code>
96 *
97 * @category   Testing
98 * @package    PHPUnit
99 * @author     Sebastian Bergmann <sb@sebastian-bergmann.de>
100 * @copyright  2002-2005 Sebastian Bergmann <sb@sebastian-bergmann.de>
101 * @license    http://www.opensource.org/licenses/bsd-license.php  BSD License
102 * @version    Release: 1.3.2
103 * @link       http://pear.php.net/package/PHPUnit
104 * @since      Class available since Release 1.0.0
105 */
106class PHPUnit_TestCase extends PHPUnit_Assert {
107    /**
108     * @var    boolean
109     * @access private
110     */
111    var $_failed = FALSE;
112
113    /**
114     * The name of the test case.
115     *
116     * @var    string
117     * @access private
118     */
119    var $_name = '';
120
121    /**
122     * PHPUnit_TestResult object
123     *
124     * @var    object
125     * @access private
126     */
127    var $_result;
128
129    /**
130     * Constructs a test case with the given name.
131     *
132     * @param  string
133     * @access public
134     */
135    function PHPUnit_TestCase($name = FALSE) {
136        if ($name !== FALSE) {
137            $this->setName($name);
138        }
139    }
140
141    /**
142     * Counts the number of test cases executed by run(TestResult result).
143     *
144     * @return integer
145     * @access public
146     */
147    function countTestCases() {
148        return 1;
149    }
150
151    /**
152     * Gets the name of a TestCase.
153     *
154     * @return string
155     * @access public
156     */
157    function getName() {
158        return $this->_name;
159    }
160
161    /**
162     * Runs the test case and collects the results in a given TestResult object.
163     *
164     * @param  object
165     * @return object
166     * @access public
167     */
168    function run(&$result) {
169        $this->_result = &$result;
170        $this->_result->run($this);
171
172        return $this->_result;
173    }
174
175    /**
176     * Runs the bare test sequence.
177     *
178     * @access public
179     */
180    function runBare() {
181        $this->setUp();
182        $this->runTest();
183        $this->tearDown();
184        $this->pass();
185    }
186
187    /**
188     * Override to run the test and assert its state.
189     *
190     * @access protected
191     */
192    function runTest() {
193        call_user_func(
194          array(
195            &$this,
196            $this->_name
197          )
198        );
199    }
200
201    /**
202     * Sets the name of a TestCase.
203     *
204     * @param  string
205     * @access public
206     */
207    function setName($name) {
208        $this->_name = $name;
209    }
210
211    /**
212     * Returns a string representation of the test case.
213     *
214     * @return string
215     * @access public
216     */
217    function toString() {
218        return '';
219    }
220
221    /**
222     * Creates a default TestResult object.
223     *
224     * @return object
225     * @access protected
226     */
227    function &createResult() {
228        return new PHPUnit_TestResult;
229    }
230
231    /**
232     * Fails a test with the given message.
233     *
234     * @param  string
235     * @access protected
236     */
237    function fail($message = '') {
238        if (function_exists('debug_backtrace')) {
239            $trace = debug_backtrace();
240
241            if (isset($trace['1']['file'])) {
242                $message = sprintf(
243                  "%s in %s:%s",
244
245                  $message,
246                  $trace['1']['file'],
247                  $trace['1']['line']
248                );
249            }
250        }
251
252        $this->_result->addFailure($this, $message);
253        $this->_failed = TRUE;
254    }
255
256    /**
257     * Passes a test.
258     *
259     * @access protected
260     */
261    function pass() {
262        if (!$this->_failed) {
263            $this->_result->addPassedTest($this);
264        }
265    }
266
267    /**
268     * Sets up the fixture, for example, open a network connection.
269     * This method is called before a test is executed.
270     *
271     * @access protected
272     * @abstract
273     */
274    function setUp() { /* abstract */ }
275
276    /**
277     * Tears down the fixture, for example, close a network connection.
278     * This method is called after a test is executed.
279     *
280     * @access protected
281     * @abstract
282     */
283    function tearDown() { /* abstract */ }
284}
285
286/*
287 * Local variables:
288 * tab-width: 4
289 * c-basic-offset: 4
290 * c-hanging-comment-ender-p: nil
291 * End:
292 */
293?>
294