| Author: | Roman Neuhauser |
|---|---|
| Contact: | neuhauser@sigpipe.cz |
| Copyright: | This document has been placed in the public domain. |
| Id: | reference.rest 498 2008-06-03 05:45:17Z roman |
| HeadURL: | $HeadURL: https://svn.sigpipe.cz/r/trunk/testilence/docs/reference.rest $ |
The library code is organized into six circuits (with some overlaps): testing, organization, execution, evaluation, reporting, and presentation.
The testing circuit contains these important classes: Tence_TestCase, Tence_Assertion (there's more but those are private parts).
Organization comprises Tence_TestSuite, Tence_TestCase classes, and the Tence_TestCollection interface.
Execution includes the Tence_RunnableTest interface, and the Tence_TestCaseClass class.
The evaluation, reporting, and presentation circuits are still too raw for documentation.
Tence_TestCase is an abstract base class you're welcome to use as the parent of your test cases. However, any class that implements Tence_RunnableTest (and optionally Tence_TestCollection) will do. Tence_TestCase provides a handful of assertion methods and provides a very concise interface for exception testing.
Tence_TestCaseClass helps keep the number of non-assertion methods in Tence_TestCase as low as possible, a sort of proxy for Tence_TestCase, identifies test methods in the test case instance.
Tence_Assertion transports details of test method execution from the case into outside world. Instances of this class are virtually invisible to normal Testilence users, the class is mentioned here to prevent confusion later as it appears a lot in the Tence_TestCase's synopsis.
Possible test results are:
A "test" consists of calls to setUp(), the test method, and tearDown(). All three are considered during evaluation of the test, the formula is:
Interface through which the tests are run.
void Tence_RunnableTest::run(Tence_Reporter $reporter)
Interface for access to components of a composite test.
Tence_RunnableTest[] Tence_TestCollection::getTests()
| implements: | Tence_RunnableTest |
|---|
| implements: | Tence_RunnableTest, Tence_TestCollection |
|---|
Abstract base for test case classes.
Intent of this class is to provide comfortable environment for robust tests. To this end, Tence_TestCase provides a set of assertion methods. A test case class inherits Tence_TestCase. It can define any number of test methods, and optionally either or both of setUp() and tearDown(). It should not define any constructor or destructor methods: the library is free to create and destroy suite and case instances without actually running them.
public final function __construct() { ... }
public final function __destruct() { ... }
Instances of Tence_TestCase's subclasses must be default constructible, and carry no state outside of the setUp()-tearDown() interval. Tence_TestCase has final constructor and destructor to enforce this policy.
public Tence_Assertion Tence_TestCase::testXXX()
Any public nullary method whose name begins with "test" is considered a test method, and must return an instance of Tence_Assertion. Failing to do so results in the test method being marked as defective. The reasons behind this requirement are better tests and better code.
Important part of robustness in tests is isolation: any test that depends on things it doesn't control is fragile. This library guarantees that each test method will be called on a separate test case instance.
public void Tence_TestCase::setUp() public void Tence_TestCase::tearDown()
setUp() and/or tearDown() can be used for setup and cleanup tasks common to all test methods of the test case. setUp() is called before every test method, tearDown() afterwards, both on the same instance as the test method.
If setUp() throws, tearDown() is run immediately. The test method is skipped. If either of these two methods throws, the test method is marked as defective. Exceptions thrown from setUp() mute all exceptions thrown from tearDown().
Note
None of the assertFoo() methods performs any type conversions on the tested values. This eliminates a few false negatives: for example, 0 == false, but their string representations differ drammaticaly ("0" vs. ""); the sooner this kind of things is caught the better.
assertTrue(1) will fail, as will assertEquals(1, "1")!
Checks that $act equals $exp.
Instances of the same class are compared by value (using the == operator).
Checks that $act equals $exp.
Instances of the same class are compared by identity (using the === operator).
Alias: void Tence_TestCase::setExpectedException($type)
Iff the code following the call of this method throws an exception that is instanceof $type, the test method will "return" successful assertion. All other outcomes cause a failure.
Actual return value of this test method (if any) will be ignored.
This class provides safe temporary files. The file is created in the constructor with:
fopen(..., 'x+')
which should translate to open(..., O_EXCL|O_CREAT), and removed in the destructor.
$dir (falls back to getenv("TMPDIR") and "/tmp" if null) is used as the directory component of the path of the file being created.
$generator defaults to a fresh instance of Tence_util_UniqueFilenameGenerator.
Throws RuntimeException if $dir is wrong, or if mkdir() fails. Throws Tence_util_GeneratorExhausted if a unique filename cannot be found within the configured number of attempts.
This class provides temporary directories. The directory is created in the constructor, and recursively removed in the destructor.
$dir (falls back to getenv("TMPDIR") and "/tmp" if null) is used as the directory component of the path of the directory being created.
$generator defaults to a fresh instance of Tence_util_UniqueFilenameGenerator.
Throws RuntimeException if $dir is wrong, or if fopen() fails. Throws Tence_util_GeneratorExhausted if a unique filename cannot be found within the configured number of attempts.