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. This feature has been heavily inspired by Ruby On Rails (http://www.rubyonrails.org) test database support and makes setting up test databases a breeze.

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

This is an example testcase using the test database and adding data with sql statements. You can place your testcase in the testcases/ dir of your module.

  /**
   * One line description of the class
   *
   * Full description of the class
   *
   * @author Dennis-Jan Broerse <dennisjan@ibuildings.nl>
   * @package package
   * @subpackage subpackage
   *
   */
  class test_representatie extends atkTestCase 
  {
  
    /**
     * Before every test function the setup function has been called.
     *
     */
    function setUp()
    {
      parent::setUp();  
      
      $db = &atkGetDb();
      
      $sql = "insert into booking_representatie values('9','','dj','dj','djrepresentatie','dj')"; //Insert some records
      
      $db->query($sql);
    }
    
    //Here you can insert your test methods
    
    /**
     * One line description of the function
     *
     * Full description of the function
     *
     */
     function test_getRepresentations()
     {
       $this->assertEqual(getRecord(),'djrepresentatie', 'Representatie is djrepresentatie'); // Get the record and test it
     }
  
    /**
     * After every test function the teardown function has been called.
     *
     */
    function tearDown()
    {
      parent::tearDown();
    } 
  
  }

This is an example testcase using the test database and adding data with fixtures.

/**
   * One line description of the class
   *
   * Full description of the class
   *
   * @author Dennis-Jan Broerse <dennisjan@ibuildings.nl>
   * @package package
   * @subpackage subpackage
   *
   */
  class test_representatie extends atkTestCase 
  {
    /**
     * Constructor.
     */
    public function __construct()
    {
      parent::__construct(); // not really necessary now, but might be in the future
      $this->addFixture('module.table');
    }

    // Here you can insert your test methods
    
    /**
     * One line description of the function
     *
     * Full description of the function
     */
    public function test_getRepresentations()
    {
      $this->assertEqual(getRecord(),'djrepresentatie', 'Representatie is djrepresentatie');
    }
  }

Creating fixtures

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 (make a fixture for db_sequence as well). 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 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.

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.

Example

Fixtures are placed in the testcases/fixtures/ directory of your module. The fixture gets the exact same name as the table you want to insert rows in. E.g. if you want to fill a table named 'booking', you create a file named booking.yml, which may look like this:

booking1:
 id: 1
 site: site1
 resort: resort1

booking2:
 id: 2
 site: site1
 resort: resort1

booking3:
 id: 3
 site: site2
 resort: resort1

In the setUp() function of your atkTestCase you add the fixture by calling $this->addFixture('yourmodule.yourfixture'):

$this->addFixture('booking_module.booking');

After this call, your booking-table contains the records specified in your fixture-file.