| Author: | Roman Neuhauser |
|---|---|
| Contact: | neuhauser@sigpipe.cz |
| Copyright: | This document has been placed in the public domain. |
| Id: | $Id$ |
| HeadURL: | $HeadURL$ |
Testilence is an open-source [1] unit testing library for PHP [2] 5. It is published under the MIT license [3] which means you are free and welcome to use it in any way. Like other JUnit [4]-inspired unit testing libraries, Testilence roughly follows the canon [5]. It is however written with emphasis on what's useful, not what's usual, and combines original ideas with the best features found in different unit-testing toolkits into a coherent set.
Testilence differs from the above-mentioned canon in that you only get to have one assertion per test method (this is a Good Thing):
Testilence features highly isolated tests with deterministic execution [6] and guaranteed cleanup [7].
Testilence is an essential ingredient in BEER [8].
Testilence is in early stages of development, output of the command line tool lacks lots of essential information, and the reporting and presentation circuits [9] of the library need much work. Test isolation is still not perfect: environment, installed functions and classes, error handler, etc. still carry over from previous tests; certain forms of misuse will kill the command line tool with a fatal error.
That said, Testilence is already quite usable, and has gone through lots or realworld use.
The smallest unit of tests is the test case class. It defines any number of test methods, and optionally either of setUp and tearDown methods (or both). Testilence provides an abstract test case base class with a number of assertFoo() methods, and a test suite class which allows arbitrary nesting of cases and suites, thanks to the Composite organization.
Runtime behavior is illustrated with the following simplified snippet of pseudocode.
$suite = new my_suite
for each $case in $suite do:
for each $test in $case do:
$o = new $case
set_up $o
$test $o
tear_down $o
done
done
Note that each test method is run on a separate instance.
Basic guarrantee: Testilence is developed and tested on FreeBSD 6 with PHP 5.1.[3-6], and 5.2.[0-9], the Makefile is tested (no automation yet) with the system make (should work on any BSD) and GNU make, and on RHEL 4 with PHP 5.1.4 and 5.2.0, and GNU make.
Testilence on Microsoft Windows requires MSYS [10].
The build and installation mechanism requires a subset of the POSIX shell environment, plus make.
Repository checkouts require Docutils [11] to build HTML documentation.
The Testilence library has the following runtime requirements:
PHP >= 5.1.3 (with PCRE, Reflection, SPL)
Testilence works with 5.1.3 or higher. Expect a bump to 5.2.0 (for better __toString() behavior). Expect addition of any of these PHP modules: operator [12], pcntl [13], posix [14], runkit [15], xdebug [16].
BSD, Linux, or UNIX
This is a conservative statement.
Some features might be missing on non-POSIX systems. Testilence is written with preference for portability, and should work on Microsoft Windows as is. Windows is, however, a second-tier operating system, problems are bound to appear from time to time.
The Testilence command line interface, tence, requires a subset of the POSIX shell environment. Besides that, its runtime requirements are the same as the library requirements, plus:
Console_Getopt [17] from PEAR
Expect this to change to a different library.
Note: the POSIX shell requirement means tence doesn't work in the command line interpreters found in Microsoft Windows (command.com and cmd.exe), and needs to be run from the MSYS [10] shell instead.
The latest source get be checked out from the Mercurial [18] repository [19], which is also available for anonymous browsing [20].
Testilence source releases are distributed as bzip2ed tarballs created with either Tim Kientzle's bsdtar [21] or GNU tar, Julian Seward's bzip2 [22] in all cases. Your operating system should include compatible extraction tools.
All Testilence releases can be found in the download directory [23].
The most comfortable way to install Testilence is using your operating system's packaging system. Ask your OS vendor for a package of the latest Testilence release.
The source distribution includes a FreeBSD port skeleton.
% url=http://www.testilence.org/dist/testilence-x.y.x.tar.bz2 % fetch -o - $url | tar -xjf - % cd testilence-x.y.z % ./configure % make check % sudo make install
The build and installation process can be configured using a number of make variables. Defaults should just work on most computers.
configure options:
--prefix=path
Install location prefix. All installation paths are based on this one unless overriden by more specific variables. Substituted into built files.
Default: /usr/local
--bindir=path
Installation directory for executable programs.
Default: ${TENCE_PREFIX}/bin
--docsdir=path
Installation directory for reST and HTML documentation.
Default: ${TENCE_PREFIX}/share/doc/testilence
--man1dir=path
Installation directory for section 1 manual pages.
Default: ${TENCE_PREFIX}/man/man1
--sitepkgdir=path
Installation directory for the Testilence and tence libraries. configure detects this using include_path of the interpreter selected with --with-php.
Default: system-specific
--testdir=path
Installation directory for Testilence's test suite.
Default: ${TENCE_PREFIX}/share/pear/tests/Testilence
--with-php=cmd
Path to the PHP CLI. This value has two uses: it is substituted into tence, and used in the check targets to run the tests.
Default: /usr/bin/env php
Makefile variables:
Install location prefix. All installation paths are prefixed with this one. This variable is used only during the install step, and is not substituted into any files.
Default: '' (empty string)
Functionality not described above or in the builtin help should be considered implementation details. If the documented features don't support all your configuration needs, please do send a feature request.
Testilence can be built and installed using the MSYS shell.
Testilence's own test suite can be exercised with or without installed Testilence by running make check or make check-all in the source directory. The former target excludes tests that use filesystem or other external resources, because a bug in Testilence might prevent proper cleanup or (although unlikely) delete your files. The tests will be run using src/tence/tence (will be built if necessary).
The test suite is described in more detail in Test Suite.
The suite is organized around Testilence's classes, meaning there is one or more cases per class under test. These are in turn organized into suites, possibly multiple levels of them. Any part of the resulting tree can be run.
The top level suite is called tencetest_AllTests. This suite contains tencetest_SafeTests and tencetest_DangerousTests.
Source code for the complete suite can be found in the tests [24] subdirectory in the source distribution.
Testilence consists of a library and a command line test runner. The library is perfectly usable without the tool.
tence, the command line frontend, is documented in the accompanying man page.
Source code for the command line tool can be found in the src/tence [25] subdirectory in the source distribution.
Testilence Library Reference [26] describes public interfaces and behaviors.
Source code for the library can be found in the src/Testilence [27] subdirectory in the source distribution.
Testilence Usage Examples [28] illustrate usage of Tence_TestCase [29] and Tence_TestSuite [30] in writing tests, and tence for their execution.
Testilence releases fall into one of the following four categories:
Each release is tagged with a version number string with the following structure (ABNF [31]):
version-string = compat-cnt "." newfun-cnt "." bugfix-cnt [rel-candidate] compat-cnt = counter newfun-cnt = counter bugfix-cnt = counter rel-candidate = "." snapshot counter ; "snap" snapshot = %x73.6e.61.70 ; counter is a positive integer (includes 0) counter = 1 * DIGIT
For each release of any type the appropriate counter is incremented by at least one and counters to the right of it are reset to 0 (the release-candidate part is removed altogether), while counters to the left of it are left at their current values.
Version string of the first nonsnapshot Testilence release is 0.0.0, while "0.0.0.snap135" is the version string of a pre-0.0.0 snapshot. There may be gaps between.
This handling is consistent with the way FreeBSD's pkg_version -t [32] interprets version strings.
| [1] | http://opensource.org/docs/definition.php |
| [2] | http://www.php.net/ |
| [3] | http://opensource.org/licenses/mit-license.php |
| [4] | http://www.junit.org/ |
| [5] | http://www.xprogramming.com/testfram.htm |
| [6] | docs/reference.rest#test-methods |
| [7] | docs/reference.rest#setup-and-teardown |
| [8] | http://beer.sigpipe.cz/ |
| [9] | docs/reference.rest#overview |
| [10] | (1, 2, 3, 4) http://mingw.org/msys.shtml |
| [11] | http://docutils.sourceforge.net/ |
| [12] | http://pecl.php.net/package/operator |
| [13] | http://php.net/manual/en/ref.pcntl.php |
| [14] | http://php.net/manual/en/ref.posix.php |
| [15] | http://pecl.php.net/package/runkit |
| [16] | http://www.xdebug.org/ |
| [17] | http://pear.php.net/package/Console_Getopt |
| [18] | http://selenic.com/mercurial/ |
| [19] | https://hg.sigpipe.cz/ |
| [20] | http://hg.sigpipe.cz/ |
| [21] | http://people.freebsd.org/~kientzle/libarchive/ |
| [22] | http://www.bzip.org/ |
| [23] | http://www.testilence.org/dist/ |
| [24] | tests/ |
| [25] | src/tence/ |
| [26] | docs/reference.rest |
| [27] | src/Testilence/ |
| [28] | docs/examples.rest |
| [29] | docs/reference.rest#tence-testcase |
| [30] | docs/reference.rest#tence-testsuite |
| [31] | http://tools.ietf.org/html/rfc4234 |
| [32] | http://www.freebsd.org/cgi/man.cgi?query=pkg_version |