Merge branch 'improve-unit-test-docs' into 'dev'

Improve docs for UnitTestCase class.

See merge request hubzilla/core!2122

1 files changed, 54 insertions, 11 deletions

diff --git a/tests/unit/UnitTestCase.php b/tests/unit/UnitTestCase.php
index a4ea94b13..9ab6a534a 100644
--- a/tests/unit/UnitTestCase.php
+++ b/tests/unit/UnitTestCase.php
@@ -33,29 +33,30 @@ require_once __DIR__ . '/../../boot.php';
 require_once 'include/dba/dba_driver.php' ;
 
 /**
- * @brief Base class for our Unit Tests.
+ * Base class for our Unit Tests.
  *
- * Empty class at the moment, but you should extend this class for unit test
- * cases, so we could and for sure we will need to implement basic behaviour
- * for all of our unit tests.
+ * Base class for Hubzilla unit/integration tests. This extends the base
+ * TestCase class from PHPUnit by connecting to a test database, and making the
+ * database connection available to the code under test via the normal Hubzilla
+ * mechanisms, i.e the \DBA::$dba global variable.
  *
- * @author Klaus Weidenbach
+ * It also automatically loads database fixtures from yaml files in the
+ * tests/unit/includes/dba/_files directory. And wraps each test run in it's
+ * own database transaction.
  */
 class UnitTestCase extends TestCase {
 	protected array $fixtures = array();
 
 	/**
-	 * Override the PHPUnit\Framework\TestCase::run method, so we can
-	 * wrap it in a database transaction.
+	 * Override the run method, so we can wrap it in a database transaction.
+	 *
+	 * The transaction is automatically rolled back when the test completes, to
+	 * leave the test database in a known pristine state.
 	 *
 	 * @SuppressWarnings(PHPMD.UnusedLocalVariable)
 	 */
 	public function run(TestResult $result = null): TestResult {
-		// $myclass = get_class($this);
-		// logger("[*] Running test: {$myclass}::{$this->getName(true)}", LOGGER_DEBUG);
-
 		if (! \DBA::$dba) {
-			//logger('[*] Connecting to test db...');
 			$this->connect_to_test_db();
 		}
 
@@ -74,6 +75,22 @@ class UnitTestCase extends TestCase {
 		return $result;
 	}
 
+	/**
+	 * Connect to the test database,
+	 *
+	 * By default it will connect to a MySQL database with the following settings:
+	 *
+	 *   - HZ_TEST_DB_HOST: db
+	 *   - HZ_TEST_DB_PORT: default
+	 *   - HZ_TEST_DB_USER: test_user
+	 *   - HZ_TEST_DB_PASS: hubzilla
+	 *   - HZ_TEST_DB_DATABASE: hubzilla_test_db
+	 *   - HZ_TEST_DB_TYPE: mysql (can also be "postgres")
+	 *   - HZ_TEST_DB_CHARSET: UTF8
+	 *
+	 * All of these settings can be overridden by the test runner by setting ENV vars
+	 * named as above with the values you want to override.
+	 */
 	protected function connect_to_test_db() : void {
 		if ( !\DBA::$dba ) {
 			\DBA::dba_factory(
@@ -101,6 +118,14 @@ class UnitTestCase extends TestCase {
 		}
 	}
 
+	/**
+	 * Return the database type from a string.
+	 *
+	 * @param string $type	The database type, can be either mysql or postgres.
+	 *
+	 * @return The database type constant matching the passed in type, or DBTYPE_MYSQL
+	 *			if $type is empty or invalid.
+	 */
 	private static function dbtype(string $type): int {
 		if (trim(strtolower($type)) === 'postgres') {
 			return DBTYPE_POSTGRES;
@@ -109,6 +134,9 @@ class UnitTestCase extends TestCase {
 		}
 	}
 
+	/**
+	 * Load database fixtures from the fixture path.
+	 */
 	private function loadFixtures() : void {
 		$files = glob(__DIR__ . '/includes/dba/_files/*.yml');
 		if ($files === false || empty($files)) {
@@ -117,6 +145,21 @@ class UnitTestCase extends TestCase {
 		array_walk($files, fn($file) => $this->loadFixture($file));
 	}
 
+	/**
+	 * Load database fixtures from a specific file.
+	 *
+	 * The file must be a yaml file named the same as the table in the database
+	 * it should populate.
+	 *
+	 * The file also need to have a root key with the same name as the table.
+	 * Under which it contains an array of rows that should be inserted into
+	 * the db table.
+	 *
+	 * @param string $file	The path and filename of the fixture to load.
+	 *						The path name is relative to the current working
+	 *						directory of the process, which should normally
+	 *						be the Hubzilla root directory.
+	 */
 	private function loadFixture($file) : void {
 		$table_name = basename($file, '.yml');
 		$this->fixtures[$table_name] = yaml_parse_file($file)[$table_name];