cspray/database-testing-amphp-postgres

Amphp Postgres ConnectionAdapter for cspray/database-testing

dev-main 2025-08-20 13:53 UTC

Requires

• php: ^8.3
• amphp/postgres: ^2.1
• cspray/database-testing: 0.5

Requires (Dev)

• phpunit/phpunit: ^11.5
• roave/security-advisories: dev-latest

MIT

README

A connection adapter for cspray/database-testing that allows you to use an Amphp Postgres connection for testing database interactions.

Installation

Composer is the only supported means to install this package.

composer require --dev cspray/database-testing-amphp-postgres

Quick Start

This library works by providing an implementation of the Cspray\DatabaseTesting\ConnectionAdapter\ConnectionAdapter interface and Cspray\DatabaseTesting\ConnectionAdapter\ConnectionAdapterFactory implementations designed to work with PostgreSQL. Check out the example below to quickly get started!

Examples below will use code from the cspray/database-testing-phpunit extension. If you're using a different testing framework you may need to adjust your code as appropriate.

Postgres

<?php declare(strict_types=1);

namespace Cspray\DatabaseTesting\Amphp\Postgres\Demo;

use Amp\Postgres\PostgresConnection;
use Cspray\DatabaseTesting\ConnectionAdapter\ConnectionAdapterConfig;
use Cspray\DatabaseTesting\DatabaseCleanup\TransactionWithRollback;
use Cspray\DatabaseTesting\RequiresTestDatabase;
use Cspray\DatabaseTesting\Amphp\Postgres\PostgresAmphpConnectionAdapterFactory;
use PHPUnit\Framework\TestCase;

#[RequiresTestDatabase(
    new PostgresAmphpConnectionAdapterFactory(new ConnectionAdapterConfig(
        'my_database',
        '127.0.0.1',
        5432,
        'my_user',
        'my_password'
    )),
    new TransactionWithRollback()
)]
final class PostgresDemoTest extends TestCase {

    #[InjectTestDatabase]
    private static TestDatabase $testDatabase;

    private PostgresConnection $postgres;
    private MyRepository $myRepository;

    protected function setUp() : void {
        // be sure to use the connection from TestDatabase! depending on CleanupStrategy,
        // using a different connection could wind up with a dirty database state
        $this->postgres = self::$testDatabase->connection();
        $this->myRepository = new MyRepository($this->postgres);
    }
    
    // populate with more appropriate data. recommended to implement your own 
    // Cspray\DatabaseTesting\Fixture\Fixture to reuse datasets across tests
    #[LoadFixture(
        new SingleRecordFixture('my_table', [
            'name' => 'cspray',
            'website' => 'https://cspray.io'
        ])
    )]
    public function testTableHasCorrectlyLoadedFixtures() : void {
        $table = self::$testDatabase->table('my_table');
        
        self::assertCount(1, $table);
        
        self::assertSame('cspray', $table->row(0)->get('name'))
        self::assertSame('website', $table->row(0)->get('website'));
    }
    
    public function testTableCanBeReloadedToGetNewlyInsertedRecords() : void {
        $table = self::$testDatabase->table('my_table');
        
        self::assertCount(0, $table);
        
        $this->myRepository->save(new MyEntity());
    
        $table->reload();
        
        self::assertCount(1, $table);
    }
}

Running Tests

By the nature of this library, we need to interact with a database during our tests. This presents some challenges and concessions that otherwise wouldn't be present when writing tests. Most importantly, that means we need to have multiple running database servers. To run tests for this library you must use docker compose run --rm tests. This will ensure the appropriate database servers are up and running so tests have something to connect to.