Add grabEntryFromDatabase and grabEntriesFromDatabase methods

* feat: mysql helper to grab entire rows

* fix: use semantic assertions

* feat: grabEntryFromDatabase makes the test fail if no row is found

* misc: code style

* Fix syntax error made while resolving conflict

Co-authored-by: Gintautas Miselis <gintautas@miselis.lt>

Author: JesusTheHun

src/Codeception/Module/Db.php

@@ -729,7 +729,7 @@ public function _loadDump(string $databaseKey = null, array $databaseConfig = nu
         $databaseKey = empty($databaseKey) ?  self::DEFAULT_DATABASE : $databaseKey;
         $databaseConfig = empty($databaseConfig) ?  $this->config : $databaseConfig;
 
-        if ($databaseConfig['populator']) {
+        if (!empty($databaseConfig['populator'])) {
             $this->loadDumpUsingPopulator($databaseKey, $databaseConfig);
             return;
         }
@@ -956,6 +956,77 @@ public function grabFromDatabase(string $table, string $column, array $criteria
         return $this->proceedSeeInDatabase($table, $column, $criteria);
     }
 
+    /**
+     * Fetches a whole entry from a database.
+     * Make the test fail if the entry is not found.
+     * Provide table name, desired column and criteria.
+     *
+     * ``` php
+     * <?php
+     * $mail = $I->grabEntryFromDatabase('users', array('name' => 'Davert'));
+     * ```
+     * Comparison expressions can be used as well:
+     *
+     * ```php
+     * <?php
+     * $post = $I->grabEntryFromDatabase('posts', ['num_comments >=' => 100]);
+     * $user = $I->grabEntryFromDatabase('users', ['email like' => 'miles%']);
+     * ```
+     *
+     * Supported operators: `<`, `>`, `>=`, `<=`, `!=`, `like`.
+     *
+     * @return array Returns a single entry value
+     * @throws PDOException|Exception
+     */
+    public function grabEntryFromDatabase(string $table, array $criteria = []): array
+    {
+        $query      = $this->_getDriver()->select('*', $table, $criteria);
+        $parameters = array_values($criteria);
+        $this->debugSection('Query', $query);
+        $this->debugSection('Parameters', $parameters);
+        $sth = $this->_getDriver()->executeQuery($query, $parameters);
+
+        $result = $sth->fetch(PDO::FETCH_ASSOC, 0);
+
+        if ($result === false) {
+            throw new \AssertionError("No matching row found");
+        }
+
+        return $result;
+    }
+
+    /**
+     * Fetches a set of entries from a database.
+     * Provide table name and criteria.
+     *
+     * ``` php
+     * <?php
+     * $mail = $I->grabEntriesFromDatabase('users', array('name' => 'Davert'));
+     * ```
+     * Comparison expressions can be used as well:
+     *
+     * ```php
+     * <?php
+     * $post = $I->grabEntriesFromDatabase('posts', ['num_comments >=' => 100]);
+     * $user = $I->grabEntriesFromDatabase('users', ['email like' => 'miles%']);
+     * ```
+     *
+     * Supported operators: `<`, `>`, `>=`, `<=`, `!=`, `like`.
+     *
+     * @return array<array<string, mixed>> Returns an array of all matched rows
+     * @throws PDOException|Exception
+     */
+    public function grabEntriesFromDatabase(string $table, array $criteria = []): array
+    {
+        $query      = $this->_getDriver()->select('*', $table, $criteria);
+        $parameters = array_values($criteria);
+        $this->debugSection('Query', $query);
+        $this->debugSection('Parameters', $parameters);
+        $sth = $this->_getDriver()->executeQuery($query, $parameters);
+
+        return $sth->fetchAll(PDO::FETCH_ASSOC);
+    }
+
     /**
      * Returns the number of rows in a database
      *

tests/unit/Codeception/Module/Db/AbstractDbTest.php

@@ -175,7 +175,7 @@ public function testLoadWithPopulator()
                 'cleanup'   => true,
             ]
         );
-        $this->module->_loadDump();
+        $this->module->_loadDump(null, $this->getConfig());
         $this->assertTrue($this->module->_isPopulated());
         $this->module->seeInDatabase('users', ['name' => 'davert']);
     }

tests/unit/Codeception/Module/Db/MySqlDbTest.php

@@ -91,6 +91,7 @@ public function testInitialQueriesAreExecuted()
 
     public function testGrabColumnFromDatabase()
     {
+        $this->module->_beforeSuite();
         $emails = $this->module->grabColumnFromDatabase('users', 'email');
         $this->assertSame(
             [
@@ -102,6 +103,55 @@ public function testGrabColumnFromDatabase()
             $emails);
     }
 
+    public function testGrabEntryFromDatabaseShouldFailIfNotFound()
+    {
+        try {
+            $this->module->grabEntryFromDatabase('users', ['email' => 'doesnot@exist.info']);
+            $this->fail("should have thrown an exception");
+        } catch (\Throwable $t) {
+            $this->assertInstanceOf(AssertionError::class, $t);
+        }
+    }
+
+    public function testGrabEntryFromDatabaseShouldReturnASingleEntry()
+    {
+        $this->module->_beforeSuite();
+        $result = $this->module->grabEntryFromDatabase('users', ['is_active' => true]);
+
+        $this->assertArrayNotHasKey(0, $result);
+    }
+
+    public function testGrabEntryFromDatabaseShouldReturnAnAssocArray()
+    {
+        $this->module->_beforeSuite();
+        $result = $this->module->grabEntryFromDatabase('users', ['is_active' => true]);
+
+        $this->assertArrayHasKey('is_active', $result);
+    }
+
+    public function testGrabEntriesFromDatabaseShouldReturnAnEmptyArrayIfNoRowMatches()
+    {
+        $this->module->_beforeSuite();
+        $result = $this->module->grabEntriesFromDatabase('users', ['email' => 'doesnot@exist.info']);
+        $this->assertEquals([], $result);
+    }
+
+    public function testGrabEntriesFromDatabaseShouldReturnAllMatchedRows()
+    {
+        $this->module->_beforeSuite();
+        $result = $this->module->grabEntriesFromDatabase('users', ['is_active' => true]);
+
+        $this->assertCount(3, $result);
+    }
+
+    public function testGrabEntriesFromDatabaseShouldReturnASetOfAssocArray()
+    {
+        $this->module->_beforeSuite();
+        $result = $this->module->grabEntriesFromDatabase('users', ['is_active' => true]);
+
+        $this->assertEquals(true, array_key_exists('is_active', $result[0]));
+    }
+
     public function testHaveInDatabaseAutoIncrementOnANonPrimaryKey()
     {
         $testData = [