Add an HTTP client dedicated to functional API testing

[dunglas]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	n/a
License	MIT
Doc PR	api-platform/docs#875

Currently, there are no very satisfactory solutions to write functional tests for web APIs built in PHP (API Platform and Symfony included):

• Mink/Behat/Behatch are BDD-oriented (which is completely fine, but doesn't fit with all projects/teams), are a bit complex to setup, have a high barrier to entry and are still not fully compatible with Symfony 4 (you need to rely on a dev version of Behat). They also lack of utilities, for database testing for instance.
• WebTestCase/BrowserKit are dedicated to webpage testing through web scraping (DOM Crawler, CSS selectors, simulation of browsers actions such as clicking or reloading a page...). Their API don't fit well with API testing. However, they benefit form the large ecosystem of PHPUnit, and give access to the numerous functional testing helpers provided by Symfony.
• External solutions that don't manipulate the Symfony Kernel (but are true HTTP clients) such as Postman or BlackFire Player require to setup a web server for the testing env and don't give access to the service container (for instance, to test if the database has been updated, or if a mail has been sent).

It's time to say hi to ApiTestCase and Test\Client! This new set of API testing utilities is built on top of the Symfony's Client test class, and implements the exact same interface than the brand new Symfony HttpClient component.

As you'll see, it also plays very well with Alice (the fixture generator with an official Symfony recipe), that gets new power in the operation!

Let's see how it looks:

namespace App\Tests;

use ApiPlatform\Core\Bridge\Symfony\Bundle\Test\ApiTestCase;
use Dunglas\UserBundle\Entity\ForgotPassword\Jti;
use Hautelook\AliceBundle\PhpUnit\RefreshDatabaseTrait;
use Lcobucci\JWT\Parser;

class UsersTest extends ApiTestCase
{
    use RefreshDatabaseTrait; // This new trait I added to HautelookAliceBundle will take care of refreshing the database content to put it in a known state between every tests

     // A simple test
    public function testCreateUser()
    {
        $client = static::createClient(); // $client implements the new Symfony's HttpClientInterface
        $response = $client->request('POST', '/api/users', ['json' => [
            'email' => 'dunglas+test@gmail.com',
            'plainPassword' => 'foo',
        ]]);
        $this->assertSame(201, $response->getStatusCode());

        $responseContent = $response->toArray();
        $this->assertStringStartsWith('/api/users/', $responseContent['@id']);

        $this->assertArraySubset([
            '@type' => 'http://schema.org/Person',
            'email' => 'dunglas+test@gmail.com',
        ], $responseContent);
        $this->assertArrayNotHasKey('password', $responseContent);
        $this->assertArrayNotHasKey('plainPassword', $responseContent);
    }

    // something more advanced, accessing the mails and the DB
    public function testChangePassword()
    {
        $client = static::createClient();
        $client->enableProfiler();
        $client->disableReboot();

        // Send the request
        $response = $client->request('POST', '/api/users/token_request', ['json' => ['username' => 'dunglas@gmail.com']]);
        $this->assertSame(202, $response->getStatusCode());

        $mailCollector = $client->getProfile()->getCollector('swiftmailer');

        // extract the JWT contained in the mail
        preg_match('#[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.?[A-Za-z0-9-_.+/=]*#', $mailCollector->getMessages()[0]->getBody(), $matches);
        $jwt = $matches[0];
        $decodedToken = (new Parser())->parse($jwt);

        // Change the password using the provided token
        $response = $client->request('PUT', $decodedToken->getClaim('sub'), [
            'json' => ['plainPassword' => 'newPassword'],
            'auth_bearer' => $jwt,
        ]);
        $this->assertSame(200, $response->getStatusCode());

        // Checks that the user have been changed
        $user = self::$container->get('test.security.helper')->getUser();
        $encoder = self::$container->get('test.security.encoder_factory')->getEncoder($user);
        $this->assertTrue($encoder->isPasswordValid($user->getPassword(), 'newPassword', $user->getSalt()));

        // Checks that the JTI has been saved
        $this->assertNotNull(
            self::$container->get('test.doctrine')->getRepository(Jti::class)->find($decodedToken->getClaim('jti'))
        );
    }
}

The following fixtures are loaded automatically. The database is reseted to a known test between every test (regardless of it fails or not) using transactions for maximum performance.

App\Entity\User:
  user_kevin:
    email: dunglas@gmail.com
    password: \$argon2i\$v=19\$m=1024,t=2,p=2\$TW9YajBjdGpUVUp4Uks1aA\$vwFQakIF9aGGoC5KjT+S3kuOYDtwtghzMuEZ/xP6FnM # maman

TODO:

• Import tests
• Write docs
• Add support for Basic auth
• Wait for Symfony 4.3

[baudev]

It could be great adding the possibility of testing objects with the Symfony Validator.
I recently created a gist (link) concerning that.

It would allow testing an object with the following assertion:

$this->assertSymfonyValidate($objectToTest);

What do you think about implementing it in ApiTestCase?

[dunglas]

@baudev I plan to add extra assertions in other PRs (like a response against a JSON Schema), but the one you're talking about should be added directly to Symfony IMHO (it can benefit to non-API Platform projects as well).

[teohhanhui]

Actually, is there any reason why this goes into API Platform instead of in Symfony? I can see that the implementation is completely decoupled from API Platform?

[dunglas]

@teohhanhui there are some API Platform specifics (JSON-LD by default), and @bendavies and I plan to add more (specific helpers to navigate in links, JSON Schema assertions...). But the current implementation could go in Symfony FrameworkBundle yes, technically speaking. That being said, I prefer to keep API-related stuff in this project, and this client is definitely API-related.

[dunglas]

I just added a nice API to deal with API errors (validation errors for instance), and Basic authentication:

namespace App\Tests;

use ApiPlatform\Core\Bridge\Symfony\Bundle\Test\ApiTestCase;
use Hautelook\AliceBundle\PhpUnit\RefreshDatabaseTrait;
use Symfony\Contracts\HttpClient\Exception\ClientExceptionInterface;

class ProjectsTest extends ApiTestCase
{
    use RefreshDatabaseTrait;

    public function testNotAbleToCreateProjectWithoutOwner()
    {
        $this->expectException(ClientExceptionInterface::class);
        $this->expectExceptionCode(400); // HTTP status code
        $this->expectExceptionMessage(<<<ERROR
users: This collection should contain 1 element or more.
users: The current logged in user must be part of the users owning this resource.
ERROR
);

        $client = static::createClient();
        $response = $client->request('POST', '/api/projects', [
            'basic_auth' => ['dunglas@gmail.com', 'maman'],
            'json' => [
                'name' => 'My project',
            ],
        ]);
        $response->getContent();
    }
}

To get these nice error messages pre-populated, and to be able to assert on them your API just have to respect the Hydra convention for errors, or the RFC 7807 one).

[bendavies]

i would prefer optional throwing (configurable?). in my tests, is manually check response codes and response content on error.

[dunglas]

@bendavies you can do it too, it's natively supported by HttpClient, just pass false to $response->getContent() and it will not throw, then you'll be able to do your custom assertions.

[bendavies]

yeah thanks i should have remembered that... (you mean false)

stale

[soyuka]

this stuff rocks