README

Application tests check the integration of all layers of the application (from routing to the responses). They are based on PHPUnit framework and have a special workflow:

Make a request
Test the response

Requirements

PHP 7.4 or higher.

Installation

The preferred way to install this extension is through composer.

Either run

composer require "geckoboom/whirlwind-application-testing" --dev

or add

 "geckoboom/whirlwind-application-testing": "*"

to the require-dev section of your composer.json file.

Defining a TestCase

To define your REST tests infrastructure you have to create a TestCase class that extends RestTestCase and implement realization for createApplication() method.

The following code defines a whirlwind application TestCase

<?php

namespace Test;

use League\Container\Container;
use Whirlwind\App\Application\Application;
use WhirlwindApplicationTesting\RestTestCase;
use App\Models\User;

abstract class TestCase extends RestTestCase
{
    protected function createApplication(): Application
    {
        $container = new Container();
        // register service providers here
        return new Application($container);
    }
}

In the above example, we have minimum configuration for making application tests

Now you can make REST tests. Just create new test and extend created earlier TestCase

<?php

namespace Test;

class UsersTest extends TestCase
{
    public function testGetById()
    {   
        $this->addAuthorizationToken('secret')
            ->get('/users/1', ['X-Test-Header' => 'Test'])
            ->assertResponseIsSuccessful()
            ->assertResponseCodeIsOk()
            ->assertHeader('Content-Type', 'application/json')
            ->assertResponseContainsJsonFragment(['id' => 1]);
    }
}

In the above example, the test add Bearer authorization token and validates if HTTP request was successful, have 200 status code and contains appropriate header and body fragment in response.

Making Requests

The TestCase simulates an HTTP client like a browser and makes requests into your Whirlwind application. By default you can access to the next HTTP methods:

get($uri, $headers = [])
getJson($uri, $headers = [])
post($uri, $data = [], $headers = [])
postJson($uri, $data = [], $headers = [])
put($uri, $data = [], $headers = [])
putJson($uri, $data = [], $headers = [])
patch($uri, $data = [], $headers = [])
patchJson($uri, $data = [], $headers = [])
delete($uri, $data = [], $headers = [])
deleteJson($uri, $data = [], $headers = [])
options($uri, $data = [], $headers = [])
optionsJson($uri, $data = [], $headers = [])

If required HTTP method absent in the list above you can make HTTP request via call() or json() method.

The full signature of the call() and json() methods

call(
    string $method,
    string $uri,
    array $parameters = [],
    array $files = [],
    array $server = [],
    ?string $content = null
)

json(
    string $method,
    string $uri,
    array $parameters = [],
    array $headers = []
)

Available Response Assertions

assertResponseIsSuccessful() check if status code in range [200, 300)
assertResponseCodeIs(int $status) check if status code equal to $status
assertResponseCodeIsOk() check if status code is 200
assertResponseCodeIsCreated() check if status code is 201
assertResponseCodeIsAccepted() check if status code is 202
assertResponseCodeIsNoContent() check if status code is 204
assertResponseCodeIsBadRequest() check if status code is 400
assertResponseCodeIsUnauthorized() check if status code is 401
assertResponseCodeIsForbidden() check if status code is 403
assertResponseCodeIsNotFound() check if status code is 404
assertResponseCodeIsNotAllowed() check if status code is 405
assertResponseCodeIsUnprocessable() check if status code is 422
assertHeader(string $name, $value = null) check if response has header $name with value $value (if not null)
assertResponseIsJson() check if response contains valid json
assertResponseContains(string $needle, bool $escape = true) check if response json contains string
assertResponseNotContains(string $needle, bool $escape = true) check if response json not contains string
assertHeaderMissing(string $name) check if response has no header with name $name
assertContainsInResponsePath(string $path, $expected)
assertResponseContainsExactJson(array $data)
assertResponseContainsJsonFragment(array $data) check if response contains $data fragment
assertResponseNotContainsExactJson(array $data)
assertResponseMatchesJsonType(array $jsonSchema, ?string $jsonPath = null) See justinrainbow/json-schema
assertResponseCount(int $count, ?string $jsonPath = null)

Fixtures

Fixtures are used to load "fake" set of data into a database for testing purpose. Fixture can depend on other fixtures (WhirlwindApplicationTesting\Fixture\Fixture::$depends property).

Defining a Fixture

To define a fixture, just create a new class that implements WhirlwindApplicationTesting\Fixture\FixtureInterface.

<?php

namespace Test\Fixture;

use Domain\User\User;
use Whirlwind\Infrastructure\Hydrator\UserHydrator;
use Whirlwind\Infrastructure\Repository\TableGateway\UserTableGateway;
use WhirlwindApplicationTesting\Fixture\EntityFixture;

class UserFixture extends EntityFixture
{
    protected string $dataFile = 'users.php';
    protected string $entityClass = User::class;
    
    public function __construct(UserHydrator $hydrator, UserTableGateway $tableGateway) 
    {
        parent::__construct($hydrator, $tableGateway);
    }   
}

Tip: Each EntityFixture is about preparing a DB table for testing purpose. You may specify appropriate realization of TableGatewayInterface in constructor as well as a Hydrator realization property. The table name encapsulates in table gateway, while hydrator uses for mapping raw results in WhirlwindApplicationTesting\Fixture\EntityFixture::$entityClass objects

The fixture data for an EntityFixture fixture is usually provided in a file located at data directory where fixture class is declared. The data file should return an array of data rows to be inserted into the table. For example:

<?php

// tests/Fixture/data/users.php
return [
    [
        'name' => 'user1',
        'email' => 'user1@example.org',
        'password' => bcrypt('secret'),
    ],
    [
        'name' => 'user2',
        'email' => 'user2@example.org',
        'password' => bcrypt('secret'),
    ],
];

Dependable fixture can be created by specifying WhirlwindApplicationTesting\Fixture\Fixture::$depends property, like the following

<?php

namespace Test\Fixture;

use Domain\User\UserProfile;
use Whirlwind\Infrastructure\Hydrator\UserHydrator;
use Whirlwind\Infrastructure\Repository\TableGateway\UserTableGateway;
use WhirlwindApplicationTesting\Fixture\EntityFixture;

class UserProfileFixture extends EntityFixture
{
    protected string $dataFile = 'user_profiles.php';
    protected string $entityClass = UserProfile::class;
    protected array $depends = [
        UserFixture::class,
    ];
    
    public function __construct(UserProfileHydrator $hydrator, UserProfileTableGateway $tableGateway) 
    {
        parent::__construct($hydrator, $tableGateway);
    }   
}

The dependency allows you to load and unload fixtures in well-defined order. In the above example UserFixture will always be loaded before UserProfileFixture.

Using Fixtures

If you are using fixtures in your test code, you need to add WhirlwindApplicationTesting\Traits\InteractWithFixtures trait and implement fixtures() method

<?php

namespace Test;

use Domain\Profile\Profile;
use Test\Fixture\UserFixture;
use Test\Fixture\UserProfileFixture;
use WhirlwindApplicationTesting\Traits\InteractWithFixtures;

class UsersTest extends TestCase
{
    use InteractWithFixtures;
    
    public function testGetById()
    {   
        $this->addAuthorizationToken('secret')
            ->get('/users/1', ['X-Test-Header' => 'Test'])
            ->assertResponseIsSuccessful()
            ->assertResponseCodeIsOk()
            ->assertHeader('Content-Type', 'application/json')
            ->assertResponseContainsJsonFragment(['id' => 1]);
    }
    
    public function fixtures(): array
    {
         return [
            'users' => UserFixtureClass::class,
            'profiles' => [
                'class' => UserProfileFixture::class,
                'depends' => [
                    UserFixture::class,
                ],
                'dataFile' => 'profile.php',
                'entityClass' => Profile::class,
            ],
        ];
    }
}

The fixtures listed in the fixtures() method will be automatically loaded before a test is executed.

geckoboom / whirlwind-application-testing

Maintainers

Details