Testing Your Database¶
The Test Class¶
In order to take advantage of the built-in database tools that CodeIgniter provides for testing, your
tests must extend CIDatabaseTestCase
:
<?php namespace App\Database;
use CodeIgniter\Test\CIDatabaseTestCase;
class MyTests extends CIDatabaseTestCase
{
. . .
}
Because special functionality executed during the setUp()
and tearDown()
phases, you must ensure
that you call the parent’s methods if you need to use those methods, otherwise you will lose much
of the functionality described here:
<?php namespace App\Database;
use CodeIgniter\Test\CIDatabaseTestCase;
class MyTests extends CIDatabaseTestCase
{
public function setUp()
{
parent::setUp();
// Do something here....
}
public function tearDown()
{
parent::tearDown();
// Do something here....
}
}
Setting Up a Test Database¶
When running database tests, you need to provide a database that can be used during testing. Instead of
using the PHPUnit built-in database features, the framework provides tools specific to CodeIgniter. The first
step is to ensure that you have set up a tests
database group in app/Config/Database.php.
This specifies a database connection that is only used while running tests, to keep your other data safe.
If you have multiple developers on your team, you will likely want to keep your credentials stored in the .env file. To do so, edit the file to ensure the following lines are present and have the correct information:
database.tests.dbdriver = 'MySQLi';
database.tests.username = 'root';
database.tests.password = '';
database.tests.database = '';
Migrations and Seeds¶
When running tests, you need to ensure that your database has the correct schema set up and that it is in a known state for every test. You can use migrations and seeds to set up your database, by adding a couple of class properties to your test.
<?php namespace App\Database;
use CodeIgniter\Test\CIDatabaseTestCase;
class MyTests extends\CIDatabaseTestCase
{
protected $refresh = true;
protected $seed = 'TestSeeder';
protected $basePath = 'path/to/database/files';
}
$refresh
This boolean value determines whether the database is completely refreshed before every test. If true, all migrations are rolled back to version 0, then the database is migrated to the latest available migration.
$seed
If present and not empty, this specifies the name of a Seed file that is used to populate the database with test data prior to every test running.
$basePath
By default, CodeIgniter will look in tests/_support/Database/Seeds to locate the seeds that it should run during testing.
You can change this directores by specifying the $basePath
property. This should not include the seeds directory,
but the path to the single directory that holds the sub-directory.
$namespace
By default, CodeIgniter will look in tests/_support/DatabaseTestMigrations/Database/Migrations to locate the migrations
that it should run during testing. You can change this location by specifying a new namespace in the $namespace
properties.
This should not include the Database/Migrations path, just the base namespace.
Helper Methods¶
The CIDatabaseTestCase class provides several helper methods to aid in testing your database.
seed($name)
Allows you to manually load a Seed into the database. The only parameter is the name of the seed to run. The seed
must be present within the path specified in $basePath
.
dontSeeInDatabase($table, $criteria)
Asserts that a row with criteria matching the key/value pairs in $criteria
DOES NOT exist in the database.
$criteria = [
'email' => 'joe@example.com',
'active' => 1
];
$this->dontSeeInDatabase('users', $criteria);
seeInDatabase($table, $criteria)
Asserts that a row with criteria matching the key/value pairs in $criteria
DOES exist in the database.
$criteria = [
'email' => 'joe@example.com',
'active' => 1
];
$this->seeInDatabase('users', $criteria);
grabFromDatabase($table, $column, $criteria)
Returns the value of $column
from the specified table where the row matches $criteria
. If more than one
row is found, it will only test against the first one.
$username = $this->grabFromDatabase('users', 'username', ['email' => 'joe@example.com']);
hasInDatabase($table, $data)
Inserts a new row into the database. This row is removed after the current test runs. $data
is an associative
array with the data to insert into the table.
$data = [
'email' => 'joe@example.com',
'name' => 'Joe Cool'
];
$this->hasInDatabase('users', $data);
seeNumRecords($expected, $table, $criteria)
Asserts that a number of matching rows are found in the database that match $criteria
.
$criteria = [
'active' => 1
];
$this->seeNumRecords(2, 'users', $criteria);