pdo-tools simplifies the build of a database for testing purposes
and allows you to easily verify the contents of a database after operations., (*1)
Specifically pdo-tools is a small PHP class extending PHPUnit_Framework_TestCase (see PHPUnit)
allowing to dynamically build entirely new test databases, with:, (*2)
- no database, schema or privileges prerequisites,
- keep the last
N built databases (customizable, for monitoring and debugging),
- easy fixtures,
- additional specific assertions,
- powerful combination of
PDO/PDOStatement mock objects and callbacks,
e.g. to mock a third-party database,
- ready-to-use with Jenkins and local PHPUnit.
Table of Contents
, (*3)
Installation
-
Class autoloading and dependencies are managed by Composer
so install it following the instructions
on Composer: Installation - *nix
or just run the following command:, (*4)
$ curl -sS https://getcomposer.org/installer | php
-
Add dependency to Himedia\PDOTools into require section of your composer.json:, (*5)
{
"require": {
"hi-media/pdo-tools": "1.*"
}
}
and run php composer.phar install from the terminal into the root folder of your project., (*6)
-
Include Composer's autoloader:, (*7)
<?php
require_once 'vendor/autoload.php';
…
, (*8)
Usage
Instantiation
Example:, (*9)
class MyTestCase extends DbTestCase
{
public function __construct($sName = null, array $aData = array(), $sDataName = '')
{
// BUILD_NUMBER environment variable is handled by Jenkins:
$iSuffix = isset($_SERVER['BUILD_NUMBER']) ? $_SERVER['BUILD_NUMBER'] : floor(microtime(true));
$sTestDbName = "tests_$iSuffix";
$aDbBuilderDsn = array(
'driver' => 'pgsql',
'hostname' => 'localhost',
'port' => 5432,
'dbname' => $sTestDbName,
'username' => 'user',
'password' => ''
);
$sDbBuildFile = '/path/to/buildfile.php';
parent::__construct($aDbBuilderDsn, array(), $sDbBuildFile);
}
}
where /path/to/buildfile.php (example here)
is a build file describing how to create a fresh database, roles/users and schemas,
with listing of fixtures to load, (*10)
Simple test
Example including:, (*11)
- fixture loading,
- comparison between result of executed SQL query, converted into CSV, and a CSV file,
- clean up
public function testSimple ()
{
// Load SQL dump file, possibly gzipped (.gz):
$this->loadSqlDumpFile('/path/to/dump.sql');
// calls to tested program…
// Asserts that SQL query result is equal to CSV file content:
$this->assertQueryResultEqualsCsv('SELECT … FROM A', '/path/to/expected.csv');
// Asserts that SQL query doesn't return any rows:
$this->assertQueryReturnsNoRows('SELECT * FROM B');
// Optional clean up:
$this->loadSqlDumpFile('/path/to/clean_up.sql');
}
where /path/to/fixture.sql is a typical SQL dump file, gzipped or not., (*12)
Note that in CSV files, following field's values are converted:, (*13)
-
'∅' ⇒ null
-
't' ⇒ true
-
'f' ⇒ false
Mocking a third-party database
In this example, successives calls to PDOStatement::fetch() method on the third-party database…, (*14)
- will return content of
/path/to/fixture.csv file like calls to PDOStatement::fetch(PDO::FETCH_ASSOC)
if initial statement of PDO::query() was 'SELECT … FROM A',
and false if no more lines in specified CSV,
- will return results of successives calls to the user callback
if initial statement of
PDO::query() was 'SELECT … FROM B'
All queries are internally normalized to simplify matching., (*15)
public function testWithMockDb ()
{
/* @var $oMockPDO \Himedia\DW\Tests\Mocks\PDO|\PHPUnit_Framework_MockObject_MockObject */
$oMockPDO = $this->getMock('Himedia\PDOTools\Mocks\PDO', array('query'));
$that = $this;
$oMockPDO->expects($this->any())->method('query')->will(
$this->returnCallback(
function ($sQuery) use ($that, $sResourcePath) {
return $that->getPdoStmtMock(
$sQuery,
array(
'SELECT … FROM A' => '/path/to/fixture.csv',
'SELECT … FROM B' => function () {
static $i = 0;
return ++$i > 10 ? false : array('id' => $i, 'name' => md5(rand()));
}
)
);
}
)
);
// injection of $oMockPDO, to mock third-party database…
// calls to tested program…
// assertions…
}
, (*16)
Documentation
API documentation
is generated by ApiGen in the doc/api folder., (*17)
$ vendor/bin/apigen -c apigen.neon
, (*18)
Change log
See CHANGELOG file for details., (*19)
, (*20)
Contributions
All suggestions for improvement or direct contributions are very welcome.
Please report bugs or ask questions using the Issue Tracker., (*21)
, (*22)
Versioning & Git branching model
For transparency into our release cycle and in striving to maintain backward compatibility,
Padocc's engine is maintained under the Semantic Versioning guidelines.
We'll adhere to these rules whenever possible., (*23)
The git branching model used for development is the one described and assisted by twgit tool: https://github.com/Twenga/twgit., (*24)
, (*25)
Copyrights & licensing
Licensed under the GNU Lesser General Public License v3 (LGPL version 3).
See LICENSE file for details., (*26)
Wallogit.com
