DEV Community: Manuel

Handmade E2E in raw PHP

Manuel — Sun, 26 Apr 2020 18:58:33 +0000

This post complements to these ones:

We have been developing an app in raw php since almost 3 years now, and since around a few months it is starting to have some testing. As you can imagine it was pretty though pushing to staging environment, test by hand and afterwards to prod, countless times I've broken something without even realizing. None realized. We wanted some kind of testing but the app was not really suitable to, and we did not have much time, so I kept telling myself eventually we will have tests. And now we have some and I am going to explain the whole process.

Just to get you in the proper context, our app may send requests to third party services and handles database connections. It has REST and SOAP implementations, and we want to test it all.

Deciding technology

My very first search in google was e2e php, and we got codeception, which does not seem bad at all, it has some REST API testing, which has almost everything we needed, and handling dumps for fixtures! So far so good at first sight.

We started writing some dummy tests, but then we realized, looking at this example in their website:

class CreateUserCest
{
    // tests
    public function createUserViaAPI(\ApiTester $I)
    {
        $I->amHttpAuthenticated('service_user', '123456');
        $I->haveHttpHeader('Content-Type', 'application/x-www-form-urlencoded');
        $I->sendPOST('/users', [
          'name' => 'davert', 
          'email' => 'davert@codeception.com'
        ]);
        $I->seeResponseCodeIs(\Codeception\Util\HttpCode::OK); // 200
        $I->seeResponseIsJson();
        $I->seeResponseContains('{"result":"ok"}');

    }
}

It is making a post request, so then, there is no way to mock anything, as soon as the index script is being executed, all mock we could have done it becomes useless since it is running in other proccess, but there must be a way!

We thought about PHP's built-in web server, but we have the same issue then. We can't mock something in our tests and then run php. We must avoid having to execute any script.

Reading this top, you can check PHPUnit is in the first position, but PHPUnit, as its name says, it is ment for unit testing, not for e2e... But then we wondered, why don't we "mock" index.php and from there we call the function called from index.php? That way we run in the same context so we can mock things.

From there, the choice was made, PHPUnit was staying with us and we were willing to give it a try.

Chosen tools

PHP-DI for handling dependencies.

Pixie for handling database connections. It is just a query builder, not to use a PDO because it would slow things down. If you use any other it is completely fine, for sure it offers the same and more things than pixie.

PHPUnit as one and only tool to test with.

Slim for handling requests, paths and responses.

As you see we just have 4 tools involved in testing, everything is going to be handmade.

Writing our first fake e2e test

But why fake e2e test? Just because we are not actually sending any request, we are going to mock index.php and run from there.

Imagine we have something like this as index.php:

<?php

$rootDir = dirname(__DIR__);

require_once "{$rootDir}/src/autoload.php";
require_once "{$rootDir}/src/di.php";

use Modules\Gym\Controllers\GymController;
use Modules\GymTrainers\Controllers\GymTrainersController;
use Modules\Trainer\Controllers\TrainerController;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;

$app = AppFactory::create();

$trainerController = $container->get(TrainerController::class);
$gymController = $container->get(GymController::class);
$gymTrainersController = $container->get(GymTrainersController::class);

$app->get('/trainer', fn(Request $request, Response $response, array $args) => $response->getBody()->write($trainerController->getTrainer($request)));
$app->post('/trainer', fn(Request $request, Response $response, array $args) => $response->getBody()->write($trainerController->createTrainer($request)));

$app->get('/gym', fn(Request $request, Response $response, array $args) => $response->getBody()->write($gymController->getGym($request)));
$app->post('/gym', fn(Request $request, Response $response, array $args) => $response->getBody()->write($gymController->createGym($request)));

$app->post('/assign', fn(Request $request, Response $response, array $args) => $response->getBody()->write($gymTrainersController->assign($request)));

$app->run();

What we want to do here is to execute either any method of any controller we have, we skip Request or Response methods because we assume they work properly, and we are not supposed to test a third party library.

Being this clear let's have a look at our first e2e test, for getGym method:

class GetGymTest extends TestCase
{

    public static function setUpBeforeClass(): void
    {
        $fixtures = include(__DIR__ . '/GymFixtures.php');
        FixtureLoader::preSuite($fixtures, 'Gym');
    }

    private Container $container;

    private array $request;

    public function setUp(): void
    {
        $containerBuilder = new ContainerBuilder();

        $commonDefinitions = include(__DIR__ . '/../../src/diDefinitions.php');

        $containerBuilder->addDefinitions(array_merge(
            Config::getConfig(),
            $commonDefinitions,
            [
                DatabaseService::class => FixtureLoader::$databaseService,
            ]));

        $this->container = $containerBuilder->build();

        FixtureLoader::load(null);

        FixtureLoader::$modelsModified = [];

        FixtureLoader::postLoad();

        $this->request = [
            'id' => 1,
        ];
    }

    public function tearDown(): void
    {
        FixtureLoader::reload();
    }

    public function testAnswersProperly()
    {
        $request = $this->createMock(ServerRequestInterface::class);
        $request->method('getQueryParams')->willReturn($this->request);

        $controller = $this->container->get(GymController::class);

        $response = json_decode($controller->getGym($request), true);

        $this->assertEquals(1, $response['gym']['id']);
        $this->assertEquals('https://forgev.com', $response['gym']['endpoint']);
    }

    public function testFailsWhenSendingUnknownGymId() 
    {
        $this->request['id'] = 31232131;

        $request = $this->createMock(ServerRequestInterface::class);
        $request->method('getQueryParams')->willReturn($this->request);

        $controller = $this->container->get(GymController::class);

        $response = json_decode($controller->getGym($request), true);
        $this->assertArrayHasKey('error', $response);
    }

    public static function tearDownAfterClass(): void
    {
        FixtureLoader::$databaseService->close();
    }

As you see we are using a class named FixtureLoader, which is explained here, but as a summary it just manages the database connection and reloading necessary fixtures after each test.

In setUp method we define all definitions for our dependency container and we mock our database service to get database service from fixture loader, we need to keep track of running queries, so we know which tables have been altered.

Having said that, we are pretty much done with our first e2e, we just need to look at any of these 2 tests, for example testAnswersProperly:

$request = $this->createMock(ServerRequestInterface::class);
$request->method('getQueryParams')->willReturn($this->request);

We need our request to be a ServerRequestInterface instance as defined in getGym signature:

public function getGym(ServerRequestInterface $request) {}

And later on we just execute the method, just like we would have called it from our index.php:

$controller->getGym($request);

As you saw this kind of tests are relatively easy, as we do not need to mock anything but a request. Now let's imagine you need to mock a third party service, how would it look like:

public function testAnswersProperly()
    {
        $request = $this->createMock(ServerRequestInterface::class);
        $request->method('getBody')->willReturn($this->request);

        $httpServiceMock = $this->createStub(HttpService::class);
        $httpServiceMock->method('curlPost')->willReturn(['room' => 1]);
        $this->container->set(HttpService::class, $httpServiceMock);

        $controller = $this->container->get(GymTrainersController::class);

        $response = json_decode($controller->assign($request), true);

        $this->assertIsNumeric($response['room']);
    }

This test is for assigning a trainer to a gym (or the other way around, as you want to think about it). And for that we need to check gym's availability, and they will answer us which room we need to use.

So we create a Stub of our HttpService and we mock curlPost method to return an array containing a room id, just like the request went fine.
And we set it in our container:

$this->container->set(HttpService::class, $httpServiceMock);

That step is really important because if we forget to do it it's like we have done nothing, we created our stub but we are not overriding it in our dependency container. And then it is pretty much like we have done previously, get the controller instance, execute the method we want to test and check the request.

You have more examples of these kind of tests in our repository.

Managing fixtures in raw PHP

Manuel — Sun, 26 Apr 2020 18:58:17 +0000

This post complements to these ones:

We have developed this solution for a MariaDB database, it may vary if you use other database.

We started managing fixtures in a way after each test we restart the whole database, but that just does work in real environments as databases get massive. So we needed a way to reload tables just when they have been modified. For this we used Pixie, which is a wrapper of PDO, but whichever you use in your projects should be enough.

Let's have a look at FixtureLoader class step by step:

class FixtureLoader
{

    public static DatabaseService $databaseService;

    public static array $modelsModified;

    public static array $modelsCharged;

    private static array $fixtures;

    private static array $modulesLoaded = [
        'Trainer' => false,
        'Gym' => false,
        'GymTrainer' => false,
    ];
}

Everything is static! So we need it to be due to how PhpUnit works by default, synchronously, meaning each test will run one after another and the same instance of FixtureLoader will be used. This does not work like that in NodeJS testing tools as Jest.

We store our DatabaseService instance, which if you come from the previous post you know where we use it and why, which models have been modified, charged, the whole fixtures array and which modules have been loaded already.

We understand as module an endpoint in our test, we have Trainers, Gyms and GymTrainers. This will be used in order to know if we need to clean the whole database again.

modelsModified and modelsCharted are positional arrays because just one test suite is going to be running at a time, so we do not need to track several suites. If we wanted to do so, we would need them to be associative arrays, so something like this:

public static array $modelsModified = [
    'Trainer' => [],
    'Gym' => [],
    'GymTrainer' => [],
];

public static array $modelsCharged = [
    'Trainer' => [],
    'Gym' => [],
    'GymTrainer' => [],
];

We tried running them with --process-isolation flag but we did not get any performace at all, hence we stuck to running them sequentially.

public static function preSuite(array $fixtures, string $module)
{
    self::$fixtures = $fixtures;

    $config = Config::getConfig();

    self::$databaseService = new DatabaseService($config['databaseConfig']);

    self::initDB($config['databaseConfig'], $module);

    self::$databaseService->connectToDb();

    self::load($fixtures);
}

This function is called from setUpBeforeClass. As you can see it just saves the fixtures we have sent, set databaseService, inits the database if needed, we will see afterwards how this is done, connects to database and load its fixtures.

Apart from all these things, we are taking a config out from apparently nowhere, right? No worries, this is not magic whatsoever, it will be explained here.

private static function initDB(array $databaseConfig, string $module)
{
    if (!self::$modulesLoaded[$module]) {
        shell_exec("mysql -u {$databaseConfig['username']} -p{$databaseConfig['password']} -h {$databaseConfig['host']} -P {$databaseConfig['port']} -e 'DROP DATABASE IF EXISTS {$databaseConfig['database']}; CREATE DATABASE {$databaseConfig['database']};'");

        shell_exec("mysql -u {$databaseConfig['username']} -p{$databaseConfig['password']} -h {$databaseConfig['host']} -P {$databaseConfig['port']} {$databaseConfig['database']} < " .
                __DIR__ .
                '/dump.sql');
        self::$modelsModified = self::$modelsCharged = [];
        self::$modulesLoaded[$module] = true;
    }
}

This is how initDB wors, if the module has not been charged yet, it reloads completely the database, apart from restarting modelsModified and modelsCharged trackers this last step is really important not to corrupt your fixtures.

And as we want the database to be restarted as less as possible, we have to set the module to loaded, so it wont be restarted again in our tests. For example, if we have multiple different test suites for the same module, the database will be created just once.

Before moving into how do we actually load the fixtures, I think it is better if we have a look at how fixtures look like:

use Modules\Gym\Factories\GymFactory;
use Modules\Trainer\Factories\TrainerFactory;

$gyms = [
    [
        'id' => 1,
        'endpoint' => 'https://forgev.com',
    ],
    [
        'id' => 2,
        'endpoint' => 'https://repeated-endpoint.com',
    ],
];

$trainers = [
    [
        'id' => 1,
        'email' => 'contact@forgdev.com',
        'gym_id' => $gyms[0]['id'],
    ],
    [
        'id' => 2,
        'email' => 'rmontoya@forgdev.com',
        'gym_id' => $gyms[1]['id'],
    ],
    'depends' => [
        GymFactory::TABLE_NAME,
    ],
];

return [
    GymFactory::TABLE_NAME => $gyms,
    TrainerFactory::TABLE_NAME => $trainers,
];

This is what will be inserted in our database. As you may have noticed these is a key in trainers called depends, this is in order to create fixtures in order, so gyms will be created before trainers.

Take your staffs sorcerers, because this is going to be rough:

public static function load(?array $fixtures)
    {
        foreach ($fixtures ?? self::$fixtures as $table => $rows) {
            if (!empty($rows['depends'])) {
                $dependencies = array_flip($rows['depends']);
                $dependencyModels = array_intersect_key($fixtures ?? self::$fixtures, $dependencies);
                $fixturesToLoad = array_diff_key($dependencyModels, self::$modelsCharged);
                self::load($fixturesToLoad);
                // Or, if you prefer an one line solution:
                // self::load(array_diff_key(array_intersect_key($fixtures ?? self::$fixtures, array_flip($rows['depends'])), self::$modelsCharged));
                unset($rows['depends']);
            }

            if (!isset(self::$modelsCharged[$table])) {
                foreach ($rows as $row) {
                    self::$databaseService->getQueryBuilder()->pdo()->query('SET FOREIGN_KEY_CHECKS = 0;');
                    self::$databaseService->getTable($table)->insert($row);
                    self::$databaseService->getQueryBuilder()->pdo()->query('SET FOREIGN_KEY_CHECKS = 1;');
                }
                self::$modelsCharged[$table] = true;
            }
        }

    }

Let's explain how the recursivity works here:

In case we depend on something, meaning we need to load other table before loading the current one, we are going to execute load again with just the models which haven't been charged yet.

depends array looks like this:

[
    GymFactory::TABLE_NAME,
]

First we need the Gym table name to be a key in the array, that's why we call array_flip.

Then, we intersect the keys from what we have in fixtures to what we need to load, so we just take the fixtures needed. Having in mind the example above, we would get from this call:

[
    'id' => 1,
    'endpoint' => 'https://forgev.com',
],
[
    'id' => 2,
    'endpoint' => 'https://repeated-endpoint.com',
],

And then we execute array_diff_key comparing it to the models already charged. That's in case gyms are already loaded, we do not need to load them again, besides if we try we will get an error due to duplicated keys. And then we are done with that tables dependencies, so we unset them.

Afterwards it comes the real loading, which is much simpler, we disable FOREIGN_KEY_CHECKS first just to avoid some warnings, though this is not completely necessary, it depends on your schema, we needed it. And then just insert the row into the table. And of course saving the table as charged not to be loaded again.

Realoding fixtures:

    public static function reload()
    {
        if (empty(self::$modelsModified)) {
            return;
        }

        $truncates = '';

        foreach (array_keys(self::$modelsModified) as $table) {
            $truncates .= "TRUNCATE TABLE {$table}; ";
            unset(self::$modelsCharged[$table]);
        }

        self::$databaseService->getQueryBuilder()->pdo()->query("SET FOREIGN_KEY_CHECKS = 0; {$truncates} SET FOREIGN_KEY_CHECKS = 1;")->closeCursor();

        self::$databaseService->getQueryBuilder()->removeEvent('after-insert');
    }

We always call this method from tearDown, so after finishing a test.

So, imagine we added a trainer in our first test, and we do not want that new trainer to be in the second test, what's why we need to reload Trainer table.

In the next method we explain how we keep track of modified tables.

We truncate all tables in one query and we set that table as not charged, since we are about to clean it.

Since such query: SET FOREIGN_KEY_CHECKS = 0; {$truncates} SET FOREIGN_KEY_CHECKS = 1; does not make any result, we need to close PDO's cursor, so we can continue making queries. And then remove the event for after insert queries, because setUp method is going to be executed and it is going to load some tables, and we do not need to keep track of those.

public static function postLoad()
    {
        self::$databaseService->getQueryBuilder()->registerEvent('after-insert',
            ':any',
            fn(QueryBuilderHandler $queryBuilder) => self::$modelsModified[$queryBuilder->getStatements()['tables'][0]] = true);

        self::$databaseService->getQueryBuilder()->registerEvent('after-update',
            ':any',
            fn(QueryBuilderHandler $queryBuilder) => self::$modelsModified[$queryBuilder->getStatements()['tables'][0]] = true);

        self::$databaseService->getQueryBuilder()->registerEvent('after-delete',
            ':any',
            fn(QueryBuilderHandler $queryBuilder) => self::$modelsModified[$queryBuilder->getStatements()['tables'][0]] = true);
    }

Pixie has some query events, so we use these in order to keep track of queries. All we need are inserts, updates and deletes, so we just save it in our modelsModified array for reloading them afterwards.

Your ORM or query builder for sure has something like that, so it should not be a big deal to implement this using your tool.

Tracking raw queries

Does not really matter how much we want to avoid writing raw SQL in our code, we will end up doing it either due to the ORM does not support your query or you do not find a proper way to do what you need. In case of Pixie, in the very last notes of the docs:
Of course Query Events don't work with raw queries.

Come on!! Give me a break, then, cannot we keep track of raw queries? Of course we can, we just have to find a way.

Remember the DatabaseService we used in our FixtureLoader? Well, that's one we just use for our e2e tests:


class DatabaseService extends \Shared\Database\DatabaseService
{

    public function connectToDb()
    {
        $connection = new PixieConnection($this->databaseConfig['driver'], [
            'host' => $this->databaseConfig['host'],
            'database' => $this->databaseConfig['database'],
            'username' => $this->databaseConfig['username'],
            'password' => $this->databaseConfig['password'],
            'port' => $this->databaseConfig['port'],
            'options' => [
                PDO::ATTR_TIMEOUT => 1,
            ],
        ]);

        $this->queryBuilder = new QueryBuilderHandler($connection, PDO::FETCH_ASSOC);
    }
}

And this QueryBuilderHandler is the real deal here, we have monkey patched query method (this is what we use to run raw queries)


class QueryBuilderHandler extends \Pixie\QueryBuilder\QueryBuilderHandler
{

    public function query($sql, $bindings = [])
    {
        ['action' => $action, 'table' => $table] = $this->getSqlInfo($sql);

        if ($action == 'UPDATE') {
            $this->statements = [
                'tables' => [
                    $table,
                ],
            ];
            $this->connection->getEventHandler()->fireEvents($this, 'after-update');
        }

        if ($action == 'INSERT' || $action == 'INSERT IGNORE') {
            $this->statements = [
                'tables' => [
                    $table,
                ],
            ];

            $this->connection->getEventHandler()->fireEvents($this, 'after-insert');
        }

        return parent::query($sql, $bindings);
    }

    private function getSqlInfo(string $sql)
    {
        $update = '/^(?<action>.*) (?<table>.*) SET/';
        $insert = '/^(?<action>.*)( IGNORE)? INTO (?<table>.*) \(/';

        preg_match($update, $sql, $matchesUpdate);
        preg_match($insert, $sql, $matchesInsert);

        return [
            'table' => $matchesUpdate['table'] ?? $matchesInsert['table'] ?? null,
            'action' => $matchesUpdate['action'] ?? $matchesInsert['action'] ?? null,
        ];
    }

}

So actually when we execute a raw query we can read it and know either if it's an update or insert. Since we do not use raw deletes in our code we do not need to keep track of them here, but if you do you just need to add the delete regex.

Hence we just need to behave the same way query does, and by that I mean fire the events we need:

$this->connection->getEventHandler()->fireEvents($this, 'after-update');

// OR

$this->connection->getEventHandler()->fireEvents($this, 'after-insert');

So any of these will get executed:

self::$databaseService->getQueryBuilder()->registerEvent('after-insert',
            ':any',
            fn(QueryBuilderHandler $queryBuilder) => self::$modelsModified[$queryBuilder->getStatements()['tables'][0]] = true);

self::$databaseService->getQueryBuilder()->registerEvent('after-update',
            ':any',
            fn(QueryBuilderHandler $queryBuilder) => self::$modelsModified[$queryBuilder->getStatements()['tables'][0]] = true);

And we can finally reload those as well! Just like if we did not use raw queries. By doing $queryBuilder->getStatements() we get information about the queries, and one of them is an array called tables, this way we can keep track of which tables have been modified in any way.

Handling multiple environments in raw PHP

Manuel — Sun, 26 Apr 2020 18:57:31 +0000

This post complements to these ones:

I can imagine you have at least 4 different environments in your app: one for developing, one for your CI, one for staging and one for production.

Let's see how we can handle them with ease.

In our case, if you come from previous posts, you know we are using PHP-DI. It's not completely necessary though, you can experiment with this solution depending on your app.

So we are going to have multiple config files outside src folder named config, in which there are going to be as many files as environments you have, for example:

ci.php
prod.php
dev.php

In which, let's say you need to specify your database credentials, so let's return something like this:

return [
    'databaseConfig' => [
        'driver' => 'mysql',
        'host' => '127.0.0.1',
        'username' => 'root',
        'password' => 'toor',
        'database' => 'database',
        'port' => 3305,
    ],
];

And then we need to load it from several places, for example in our (previously explained) FixtureLoader, for this we are going to use the following class:

class Config
{
    private static array $config = [];

    public static function getConfig()
    {
        if (!self::$config) {
            $_SERVER['PHP_ENV'] ??= 'default'; // IN CASE YOU NEED A DEFAULT ENV
            self::$config = include ("{$_SERVER['PHP_ENV']}.php");
        }

        return self::$config;
    }
}

Where does this $_SERVER['PHP_ENV'] come from?

In case you are running tests you can easily define it like PHP_ENV=e2e phpunit ...
Web server configuration

For example nginx's configuration:

server {
    ...

    fastcgi_param PHP_ENV env-desired;

    ...
}

This is quite practical since you can have multiple environments running at the same time, you just need as many web server configurations as environments you need running.

Then, you can configure your container:

$container = new DI\ContainerBuilder();

$container->useAutowiring(true);
$container->useAnnotations(false);

$container->addDefinitions([
    Config::getConfig(),
    DatabaseService::class => function (ContainerInterface $container) {
        $databaseService = new DatabaseService($container->get('databaseConfig'));
        $databaseService->connectToDb();

        return $databaseService;
    },
]);

if ($_SERVER['PHP_ENV'] == 'prod') {
    $container->enableCompilation(__DIR__ . '/cache');
}

$container = $container->build();

As you see, whenever we get DatabaseService from the container, it will get from its constructor the databaseConfig we have set in the specified environment's file.