Testing Database Code with PHPUnit

Assert both the returned value and the database side effect of a repository operation.

The objective is to understand the behavior and operational limits, not only the method name.

What It Does

Assert both the returned value and the database side effect of a repository operation.

Prerequisites

Use a dedicated development environment and sample data. Where a snippet uses an injected connection, repository, request value or mailer, supply it from your own application setup.

Example 1: Basic Use

A focused working pattern for this topic. Names such as $pdo, $authContext and $repo represent dependencies provided by the application unless initialized in the snippet.

<?php
final class DatabaseFeatureTest extends \PHPUnit\Framework\TestCase {
public function testInsertPersistsRow(): void {
    $db = new PDO('sqlite::memory:');
    $db->exec('CREATE TABLE notes (body TEXT)');
    $stmt = $db->prepare('INSERT INTO notes (body) VALUES (?)');
    $stmt->execute(['saved']);
    self::assertSame('saved', $db->query('SELECT body FROM notes')->fetchColumn());
}
}

Example 2: A Second Scenario

A second use case that adds a different operation or data flow specific to this topic.

<?php
final class ProductRepositoryTest extends PHPUnit\Framework\TestCase {
    public function testReadAfterInsert(): void {
        $db = new PDO('sqlite::memory:'); $db->exec('CREATE TABLE product (name TEXT)');
        $db->prepare('INSERT INTO product VALUES (?)')->execute(['mug']);
        self::assertSame('mug', $db->query('SELECT name FROM product')->fetchColumn());
    }
}

Example 3: Practical Checks

A practical validation, failure or deployment concern specific to this topic.

<?php
final class UniqueConstraintTest extends PHPUnit\Framework\TestCase {
    public function testDuplicateValueFails(): void {
        $db = new PDO('sqlite::memory:'); $db->exec('CREATE TABLE product (name TEXT UNIQUE)');
        $db->exec("INSERT INTO product VALUES ('mug')");
        $this->expectException(PDOException::class);
        $db->exec("INSERT INTO product VALUES ('mug')");
    }
}

Important Behavior and Edge Cases

Mocks cannot prove that SQL constraints or transaction boundaries actually work.

For production use, also account for error handling, data validation, resource limits and environment-specific driver behavior.

Comparison with Related Approaches

Common Beginner Mistakes

Key Takeaways

• Assert both the returned value and the database side effect of a repository operation.
• Mocks cannot prove that SQL constraints or transaction boundaries actually work.
• Use this workflow as a focused starting point rather than a substitute for application-level tests.

Choose this API or pattern when its exact semantics match your task, and verify the result against the database driver and runtime used by your application.