diff --git a/system/Database/MigrationRunner.php b/system/Database/MigrationRunner.php index 517688889ec6..cd96ebed9a1b 100644 --- a/system/Database/MigrationRunner.php +++ b/system/Database/MigrationRunner.php @@ -40,7 +40,8 @@ class MigrationRunner protected $table; /** - * The Namespace where migrations can be found. + * The Namespace where migrations can be found. + * `null` is all namespaces. * * @var string|null */ diff --git a/system/Test/CIUnitTestCase.php b/system/Test/CIUnitTestCase.php index 4fd3bca63016..5c462fa139f4 100644 --- a/system/Test/CIUnitTestCase.php +++ b/system/Test/CIUnitTestCase.php @@ -116,7 +116,7 @@ abstract class CIUnitTestCase extends TestCase /** * The namespace(s) to help us find the migration classes. - * Empty is equivalent to running `spark migrate -all`. + * Empty is equivalent to running `spark migrate --all`. * Note that running "all" runs migrations in date order, * but specifying namespaces runs them in namespace order (then date) * diff --git a/user_guide_src/source/dbmgmt/migration.rst b/user_guide_src/source/dbmgmt/migration.rst index ff81f4ff0708..5fc93f79aa6f 100644 --- a/user_guide_src/source/dbmgmt/migration.rst +++ b/user_guide_src/source/dbmgmt/migration.rst @@ -19,7 +19,7 @@ include migrations from all namespaces. :depth: 2 ******************** -Migration file names +Migration File Names ******************** Each Migration is run in numeric order forward or backwards depending on the @@ -81,7 +81,7 @@ Namespaces The migration library can automatically scan all namespaces you have defined within **app/Config/Autoload.php** or loaded from an external source like Composer, using the ``$psr4`` property for matching directory names. It will include all migrations -it finds in Database/Migrations. +it finds in **Database/Migrations**. Each namespace has its own version sequence, this will help you upgrade and downgrade each module (namespace) without affecting other namespaces. @@ -253,7 +253,7 @@ Class Reference .. php:method:: setNamespace($namespace) - :param string $namespace: application namespace. + :param string|null $namespace: application namespace. ``null`` is all namespaces. :returns: The current MigrationRunner instance :rtype: CodeIgniter\\Database\\MigrationRunner @@ -261,6 +261,8 @@ Class Reference .. literalinclude:: migration/007.php + .. note:: If you set ``null``, it looks for migration files in all namespaces. + .. php:method:: setGroup($group) :param string $group: database group name. diff --git a/user_guide_src/source/testing/database.rst b/user_guide_src/source/testing/database.rst index 680c0a3f3518..382b4ee4aa56 100644 --- a/user_guide_src/source/testing/database.rst +++ b/user_guide_src/source/testing/database.rst @@ -1,13 +1,13 @@ -===================== +##################### Testing Your Database -===================== +##################### .. contents:: :local: :depth: 2 The Test Class -============== +************** In order to take advantage of the built-in database tools that CodeIgniter provides for testing, your tests must extend ``CIUnitTestCase`` and use the ``DatabaseTestTrait``: @@ -21,7 +21,7 @@ of the functionality described here: .. literalinclude:: database/002.php 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 @@ -38,7 +38,7 @@ correct information:: 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, @@ -46,92 +46,123 @@ by adding a couple of class properties to your test. .. literalinclude:: database/003.php -**$migrate** +Migrations +---------- + +$migrate +^^^^^^^^ This boolean value determines whether the database migration runs before test. By default, the database is always migrated to the latest available state as defined by ``$namespace``. -If false, migration never runs. If you want to disable migration, set false. +If ``false``, migration never runs. If you want to disable migration, set ``false``. -**$migrateOnce** +$migrateOnce +^^^^^^^^^^^^ This boolean value determines whether the database migration runs only once. If you want -to run migration once before the first test, set true. If not present or false, migration +to run migration once before the first test, set ``true``. If not present or ``false``, migration runs before each test. -**$refresh** +$refresh +^^^^^^^^ -This boolean value determines whether the database is completely refreshed before test. If true, +This boolean value determines whether the database is completely refreshed before test. If ``true``, all migrations are rolled back to version 0. -**$seed** +$namespace +^^^^^^^^^^ + +By default, CodeIgniter will look in **tests/_support/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** sub-namespace but just the base namespace. + +.. important:: If you set this property to ``null``, it runs migrations from all available namespaces like ``php spark migrate --all``. + +Seeds +----- + +$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 test running. -**$seedOnce** +$seedOnce +^^^^^^^^^ This boolean value determines whether the database seeding runs only once. If you want -to run database seeding once before the first test, set true. If not present or false, database seeding +to run database seeding once before the first test, set ``true``. If not present or ``false``, database seeding runs before each test. -**$basePath** +$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 directory 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/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** sub-namespace but just the base namespace. -To run migrations from all available namespaces set this property to ``null``. - Helper Methods -============== +************** The **DatabaseTestTrait** class provides several helper methods to aid in testing your database. -**regressDatabase()** +Changing Database State +======================= + +regressDatabase() +----------------- Called during ``$refresh`` described above, this method is available if you need to reset the database manually. -**migrateDatabase()** +migrateDatabase() +----------------- -Called during ``setUp``, this method is available if you need to run migrations manually. +Called during ``setUp()``, this method is available if you need to run migrations manually. -**seed($name)** +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. +.. literalinclude:: database/006.php -.. literalinclude:: database/004.php +hasInDatabase($table, $data) +---------------------------- -**seeInDatabase($table, $criteria)** +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. -Asserts that a row with criteria matching the key/value pairs in ``$criteria`` DOES exist in the database. +.. literalinclude:: database/007.php -.. literalinclude:: database/005.php +Getting Data from Database +========================== -**grabFromDatabase($table, $column, $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. +row is found, it will only return the first one. -.. literalinclude:: database/006.php +Assertions +========== -**hasInDatabase($table, $data)** +dontSeeInDatabase($table, $criteria) +------------------------------------ -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. +Asserts that a row with criteria matching the key/value pairs in ``$criteria`` DOES NOT exist in the database. -.. literalinclude:: database/007.php +.. literalinclude:: database/004.php + +seeInDatabase($table, $criteria) +-------------------------------- + +Asserts that a row with criteria matching the key/value pairs in ``$criteria`` DOES exist in the database. + +.. literalinclude:: database/005.php -**seeNumRecords($expected, $table, $criteria)** +seeNumRecords($expected, $table, $criteria) +------------------------------------------- Asserts that a number of matching rows are found in the database that match ``$criteria``. diff --git a/user_guide_src/source/testing/database/003.php b/user_guide_src/source/testing/database/003.php index 399ddfb04425..f8097d91e7d6 100644 --- a/user_guide_src/source/testing/database/003.php +++ b/user_guide_src/source/testing/database/003.php @@ -9,7 +9,16 @@ class MyTests extends CIUnitTestCase { use DatabaseTestTrait; - protected $refresh = true; + // For Migrations + protected $migrate = true; + protected $migrateOnce = false; + protected $refresh = true; + protected $namespace = 'Tests\Support'; + + // For Seeds + protected $seedOnce = false; protected $seed = 'TestSeeder'; protected $basePath = 'path/to/database/files'; + + // ... }