Using a test database

ATK Howto: Using a test database Complexity: Intermediate Author: Peter C. Verhage <peter@ibuildings.nl>

List of other Howto's

Preface

ATK has built-in test support for a while now. But until now this didn't include support for adding, updating and/or removing test data in such a way that the development/production database isn't littered with test data. You can make use of the mock database class, but then you can't really test if the query you wrote actually works the way it's supposed to work. And you can ofcourse remove the test data in your test by writing the necessary code to do so, but this means a lot of extra work.

Fortunately there's a third option, you can make use of ATK's built-in test database support.

How it works

When the ATK test-suite starts it first clones the development/production database structure in a test database. Only the structure will be cloned, so you end up with an empty test database. After this the test-suite will start running the test-cases for your application.

Each test-case can consist of one or more test methods. Before each test method is called so called fixtures will be loaded into the database. Fixtures are a way of organizing your test data. They are a way of describing the records for your test database. After each test method has run the data will be rollbacked (or deleted depending on the capabilities of your database). Not only the data of the fixtures will be rollbacked, but also data that's been added inside the test method. This way you are in full control of the data inside the test database.

Configuration

You first need to configure a test database. You can do so by creating an entry called "test" in the $config_db section of the ATK configuration file. It might look like the following:

$config_db["test"]["driver"]                 = "mysqli";
$config_db["test"]["host"]                   = "localhost";
$config_db["test"]["db"]                     = "demo_test";
$config_db["test"]["user"]                   = "user";
$config_db["test"]["password"]               = "password"; 
$config_db["test"]["transactional_fixtures"] = true; 

Nothing out of the ordinary, except for the "transactional_fixtures" configuration option. This new option makes it possible to specify if your database supports transactions or not. This way the system knows it can clean-up the database using a simple rollback instead of having to delete all the data. If you don't specify this option ATK assumes by default that your database doesn't support transactions. You don't need to create any table in the test database, ATK will clone the database structure from the default database.

Warning: make sure that you really specify your test database for the "db" option else you might end up with an empty development or, even worse, an empty production database.

Creating a test case

Coming soon...

Creating fixtures

Fixtures are stored in files. At this time there are two kinds of fixtures ATK supports. First of all ATK supports YAML (http://www.yaml.org) fixtures and secondly ATK supports PHP fixtures. For each table in your database you can create a seperate fixtures file. Depending on the file extension (.yml or .php) ATK will automatically know how to process the fixtures file. A fixtures file can contain zero or more records. The records will be literally added to the database, so they won't be added with the addDb function of a node. This means that even sequence fields need to be assigned values. The reason for this is that this way it's much easier to create relationships between records, because you always know the exact key of the record(s) you want to reference. Fixtures can also be assigned a name, this makes it possible to retrieve the fixture data by name inside your test-case. In the future ATK might also support other kinds of fixtures, for example CSV (http://en.wikipedia.org/wiki/Comma-separated_values) fixtures.