Initial commit, support for PDO postgres

Author: cspray

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: 'Tests'
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Test
+        uses: isbang/compose-action@1.4.1
+        with:
+          compose-file: './docker-compose.yml'
+          down-flags: '--volumes'
+          services: |
+            tests

.gitignore

@@ -0,0 +1,5 @@
+.
+..
+/vendor
+.phpunit.cache
+.phpunit.result.cache

README.md

@@ -0,0 +1,143 @@
+# DatabaseTestCase
+
+A library to facilitate testing database interactions using PHPUnit 10+.
+
+Features this library currently provides:
+
+- Handles typical database setup and teardown
+- Simple representation of a table's rows
+- Mechanism for loading fixture data specific to each test
+
+Features this library **does not** currently provide, but plans to:
+
+- Semantic assertions on the state of a database
+- Representation for the information schema of a given table
+
+The rest of this document details how to install this library, make use of its `TestCase`, and what database 
+connection objects are supported out-of-the-box.
+
+## Installation
+
+[Composer](https://getcomposer.org/) is the only supported method for installing this library.
+
+```
+composer require --dev cspray/database-test-case
+```
+
+## Usage Guide
+
+Using this library starts by creating a PHPUnit test that extends `Cspray\DatabaseTestCase\DatabaseTestCase`. This class 
+overrides various setup and teardown functions provided by PHPUnit to ensure that a database connection is established 
+and that database interactions happen against a known state. The `DatabaseTestCase` requires implementations 
+to provide a `Cspray\DatabaseTestCase\ConnectionAdapter`. This implementation is ultimately responsible for calls to the 
+database required by the testing framework. The `ConnectionAdapter` also provides access to the underlying connection, 
+for example a `PDO` instance, that you can use in your code under test. Check out the section titled "Database Connections" 
+for `ConnectionAdapter` instances supported out-of-the-box and how you could implement your own.
+
+In our example, going to assume that you have a PostgreSQL database with a table that has 
+the following DDL:
+
+```postgresql
+CREATE TABLE my_table (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    username VARCHAR(255),
+    email VARCHAR(255),
+    is_active BOOLEAN
+)
+```
+
+Now, we can write a series of tests that interact with the database.
+
+```php
+<?php declare(strict_types=1);
+
+namespace Cspray\DatabaseTestCase\Demo;
+
+use Cspray\DatabaseTestCase\DatabaseRepresentation\Row;use Cspray\DatabaseTestCase\DatabaseTestCase;
+use Cspray\DatabaseTestCase\LoadFixture;use Cspray\DatabaseTestCase\SingleRecordFixture;use PDO;
+
+class MyDemoTest extends DatabaseTestCase {
+
+    // Generally speaking you shouldn't call this method yourself!
+    protected static function getConnectionAdapter() : ConnectionAdapter {
+        // Be sure to change these configuration values to match your test setup!
+        return new PdoConnectionAdapter(
+            new ConnectionAdapterConfig(
+                database: 'postgres',
+                host: 'localhost',
+                port: 5432,
+                user: 'postgres',
+                password: 'postgres'
+            ),
+            PdoDriver::Postgresql
+        );
+    }
+    
+    public function testUnderlyingConnection() : void {
+        // You'd pass the value of this method into your code under test
+        // Use a different ConnectionAdapter if you aren't working with PDO!
+        self::assertInstanceOf(PDO::class, self::getUnderlyingConnection());
+    }
+    
+    public function testShowEmptyTable() : void {
+        // DatabaseTestCase provides a method to get a representation of a database table
+        $table = $this->getTable('my_table');
+        
+        // The $table is Countable, the count represents the number of rows in the table
+        self::assertCount(0, $table);
+        
+        // The $table is iterable, each iteration yields a Row, but our database is empty!
+        self::assertSame([], iterator_to_array($table));
+    }
+    
+    // Pass any number of Fixture to have corresponding FixtureRecords inserted into 
+    // the database before your test starts
+    #[LoadFixture(
+        new SingleRecordFixture('my_table', ['username' => 'cspray', 'email' => 'cspray@example.com', 'is_active' => true]),
+        new SingleRecordFixture('my_table', ['username' => 'dyana', 'email' => 'dyana@example.com', 'is_active' => true])
+    )]
+    public function testLoadingFixtures() : void {
+        $table = $this->getTable('my_table');
+        
+        self::assertCount(2, $table);
+        self::assertContainsOnlyInstancesOf(Row::class, iterator_to_array($table));
+        self::assertSame('cspray', $table->getRow(0)->get('username'));
+        self::assertSame('dyana@example.com', $table->getRow(1)->get('email'));
+        self::assertNull($table->getRow(2));
+    }
+    
+}
+```
+
+### TestCase Hooks
+
+There are several critical things the `DatabaseTestCase` must take care of for database tests to work properly. To do that 
+we must do something in all the normally used PHPUnit `TestCase` hooks. To be clear those methods are:
+
+- `TestCase::setUpBeforeClass`
+- `TestCase::setUp`
+- `TestCase::tearDown`
+- `TestCase::tearDownAfterClass`
+
+To make sure that `DatabaseTestCase` processes these hooks correctly they have been marked as `final`. There are new 
+methods that have been provided that allow for the same effective hooks.
+
+| Old Hook | New Hook |
+| --- | --- |
+| `TestCase::setUpBeforeClass` | `DatabaseTestCase::beforeAll` |
+| `TestCase::setUp` | `DatabaseTestCase::beforeEach` |
+| `TestCase::tearDown` | | `DatabaseTestCase::afterEach` |
+| `TestCase::tearDownAfterClass` | `DatabaseTestCase::afterAll` |
+
+## Database Connections
+
+| Connection Instance         | Library                           | Database  | Implemented        | 
+|-----------------------------|-----------------------------------|-----------|--------------------|
+| `PDO`                       | [PHP PDO][pdo]                    | PostgreSQL | :white_check_mark: |
+| `PDO`                       | [PHP PDO][pdo]                    | MySQL     | :x:                |
+| `Amp\Postgres\PostgresLink` | [amphp/postgres@^2][amp-postgres] | PostgreSQL | :x:                | 
+| `Amp\Mysql\MysqlLink` | [amphp/mysql@^3][amp-mysql] | MySQL | :x: |
+
+[amp-mysql]: https://github.com/amphp/mysql
+[amp-postgres]: https://github.com/amphp/postgres
+[pdo]: https://php.net/pdo

composer.json

@@ -0,0 +1,32 @@
+{
+  "name": "cspray/database-test-case",
+  "description": "A PHPUnit TestCase for asserting expectations on a database",
+  "type": "library",
+  "keywords": [
+    "testing",
+    "database"
+  ],
+  "license": ["MIT"],
+  "require": {
+    "php": "^8.2",
+    "phpunit/phpunit": "^10.0"
+  },
+  "require-dev": {
+    "ext-pdo": "*",
+    "ext-pdo_pgsql": "*",
+    "roave/security-advisories": "dev-latest"
+  },
+  "autoload": {
+    "psr-4": {
+      "Cspray\\DatabaseTestCase\\": "src"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Cspray\\DatabaseTestCase\\Tests\\": "tests"
+    }
+  },
+  "suggest": {
+    "ext-pdo": "To enable the PdoConnectionAdapter"
+  }
+}

docker-compose.yml

@@ -0,0 +1,37 @@
+version: '3.8'
+
+services:
+  postgres:
+    build:
+      context: .
+      dockerfile: docker/postgres/Dockerfile
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    restart: unless-stopped
+    environment:
+      - POSTGRES_PASSWORD=postgres
+    networks:
+      databasetestcase:
+
+  tests:
+    build:
+      context: .
+      dockerfile: docker/php/Dockerfile
+      target: app
+    depends_on:
+      postgres:
+        condition: service_healthy
+    volumes:
+      - ./src:/app/src
+      - ./tests:/app/tests
+      - ./resources:/app/resources
+      - ./phpunit.xml:/app/phpunit.xml
+      - ./composer.json:/app/composer.json
+    networks:
+      databasetestcase:
+
+networks:
+  databasetestcase:
+
+volumes:
+  pgdata:

docker/php/Dockerfile

@@ -0,0 +1,25 @@
+FROM php:8.2.1-zts-bullseye AS php
+
+RUN apt-get update -y \
+    && apt-get upgrade -y
+
+RUN apt-get install git libsodium-dev libzip-dev libpq-dev -y
+RUN docker-php-ext-install sodium zip pdo pdo_pgsql
+
+RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini"
+
+COPY --from=composer:2.1 /usr/bin/composer /usr/bin/composer
+
+FROM php AS app
+
+RUN mkdir /app
+COPY src /app/src
+COPY tests /app/tests
+COPY composer.json phpunit.xml /app/
+
+WORKDIR /app
+
+RUN COMPOSER_ALLOW_SUPERUSER=1 composer validate \
+    && composer install --no-scripts
+
+CMD ["/app/vendor/bin/phpunit"]

docker/postgres/Dockerfile

@@ -0,0 +1,7 @@
+FROM postgres:15-bullseye
+
+COPY /resources/schemas/postgres.sql /docker-entrypoint-initdb.d/
+
+HEALTHCHECK --interval=5s --start-period=7s --retries=5 --timeout=5s CMD pg_isready -d postgres
+
+USER postgres

phpunit.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.0/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         cacheDirectory=".phpunit.cache"
+         executionOrder="depends,defects"
+         requireCoverageMetadata="true"
+         beStrictAboutCoverageMetadata="true"
+         beStrictAboutOutputDuringTests="true"
+         failOnRisky="true"
+         failOnWarning="true">
+    <testsuites>
+        <testsuite name="unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="integration">
+            <directory>tests/Integration</directory>
+        </testsuite>
+    </testsuites>
+
+    <coverage>
+        <include>
+            <directory suffix=".php">src</directory>
+        </include>
+    </coverage>
+</phpunit>

resources/schemas/postgres.sql

@@ -0,0 +1,5 @@
+CREATE TABLE my_table (
+    id      SERIAL PRIMARY KEY,
+    name    VARCHAR(255),
+    created_at      TIMESTAMP DEFAULT now()
+);

src/ConnectionAdapter.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Cspray\DatabaseTestCase;
+
+use Cspray\DatabaseTestCase\DatabaseRepresentation\Table;
+
+interface ConnectionAdapter {
+
+    public function establishConnection() : void;
+
+    public function onTestStart() : void;
+
+    public function onTestStop() : void;
+
+    public function closeConnection() : void;
+
+    public function loadFixture(Fixture $fixture, Fixture... $additionalFixture) : void;
+
+    public function getUnderlyingConnection() : object;
+
+    public function getTable(string $name) : Table;
+
+}