|
1 | | -# Testing Utilities |
| 1 | +# Testing the API |
2 | 2 |
|
3 | | -API Platform provides a set of useful utilities dedicated to API testing. |
4 | | -For an overview of how to test an API Platform app, be sure to read [the testing cookbook first](../symfony/testing.md). |
| 3 | +Once your API is up and running, it's crucial to write tests to ensure it is bug-free and to prevent future regressions. |
| 4 | +A good practice is to follow a [Test-Driven Development (TDD)](https://martinfowler.com/bliki/TestDrivenDevelopment.html) |
| 5 | +approach, where tests are written before the production code. |
5 | 6 |
|
6 | | -<p align="center" class="symfonycasts"><a href="https://symfonycasts.com/screencast/api-platform-security/api-tests?cid=apip"><img src="../symfony/images/symfonycasts-player.png" alt="Test and Assertions screencast"><br>Watch the API Tests & Assertions screencast</a></p> |
| 7 | +API Platform provides a set of helpful testing utilities to write unit tests, functional tests, and to create |
| 8 | +[test fixtures](https://en.wikipedia.org/wiki/Test_fixture#Software). |
7 | 9 |
|
8 | | -## The Test HttpClient |
| 10 | +## Testing Documentations |
9 | 11 |
|
10 | | -API Platform provides its own implementation of the [Symfony HttpClient](https://symfony.com/doc/current/components/http_client.html)'s interfaces, tailored to be used directly in [PHPUnit](https://phpunit.de/) test classes. |
11 | | - |
12 | | -While all the convenient features of Symfony HttpClient are available and usable directly, under the hood the API Platform implementation manipulates [the Symfony HttpKernel](https://symfony.com/doc/current/components/http_kernel.html) directly to simulate HTTP requests and responses. |
13 | | -This approach results in a huge performance boost compared to triggering real network requests. |
14 | | -It also allows access to the [Symfony HttpKernel](https://symfony.com/doc/current/components/http_kernel.html) and to all your services via the [Dependency Injection Container](https://symfony.com/doc/current/testing.html#accessing-the-container). |
15 | | -Reuse them to run, for instance, SQL queries or requests to external APIs directly from your tests. |
16 | | - |
17 | | -Install the `symfony/http-client` and `symfony/browser-kit` packages to enabled the API Platform test client: |
18 | | - |
19 | | -```console |
20 | | -composer require symfony/browser-kit symfony/http-client |
21 | | -``` |
22 | | - |
23 | | -To use the testing client, your test class must extend the `ApiTestCase` class: |
24 | | - |
25 | | -```php |
26 | | -<?php |
27 | | -// api/tests/BooksTest.php |
28 | | - |
29 | | -namespace App\Tests; |
30 | | - |
31 | | -use ApiPlatform\Symfony\Bundle\Test\ApiTestCase; |
32 | | - |
33 | | -class BooksTest extends ApiTestCase |
34 | | -{ |
35 | | - public function testGetCollection(): void |
36 | | - { |
37 | | - $response = static::createClient()->request('GET', '/books'); |
38 | | - // your assertions here... |
39 | | - } |
40 | | -} |
41 | | -``` |
42 | | - |
43 | | -Refer to [the Symfony HttpClient documentation](https://symfony.com/doc/current/components/http_client.html) to discover all the features of the client (custom headers, JSON encoding and decoding, HTTP Basic and Bearer authentication and cookies support, among other things). |
44 | | - |
45 | | -Note that you can create your own test case class extending the ApiTestCase. For example to set up a Json Web Token authentication: |
46 | | - |
47 | | -```php |
48 | | -<?php |
49 | | -// api/tests/AbstractTest.php |
50 | | -namespace App\Tests; |
51 | | - |
52 | | -use ApiPlatform\Symfony\Bundle\Test\ApiTestCase; |
53 | | -use ApiPlatform\Symfony\Bundle\Test\Client; |
54 | | -use Hautelook\AliceBundle\PhpUnit\RefreshDatabaseTrait; |
55 | | - |
56 | | -abstract class AbstractTest extends ApiTestCase |
57 | | -{ |
58 | | - private ?string $token = null; |
59 | | - |
60 | | - use RefreshDatabaseTrait; |
61 | | - |
62 | | - public function setUp(): void |
63 | | - { |
64 | | - self::bootKernel(); |
65 | | - } |
66 | | - |
67 | | - protected function createClientWithCredentials($token = null): Client |
68 | | - { |
69 | | - $token = $token ?: $this->getToken(); |
70 | | - |
71 | | - return static::createClient([], ['headers' => ['authorization' => 'Bearer '.$token]]); |
72 | | - } |
73 | | - |
74 | | - /** |
75 | | - * Use other credentials if needed. |
76 | | - */ |
77 | | - protected function getToken($body = []): string |
78 | | - { |
79 | | - if ($this->token) { |
80 | | - return $this->token; |
81 | | - } |
82 | | - |
83 | | - $response = static::createClient()->request('POST', '/login', ['json' => $body ?: [ |
84 | | - 'username' => ' [email protected]', |
85 | | - 'password' => '$3cr3t', |
86 | | - ]]); |
87 | | - |
88 | | - $this->assertResponseIsSuccessful(); |
89 | | - $data = $response->toArray(); |
90 | | - $this->token = $data['token']; |
91 | | - |
92 | | - return $data['token']; |
93 | | - } |
94 | | -} |
95 | | -``` |
96 | | - |
97 | | -Use it by extending the `AbstractTest` class. For example this class tests the `/users` resource accessibility where only the admin can retrieve the collection: |
98 | | - |
99 | | -```php |
100 | | -<?php |
101 | | -namespace App\Tests; |
102 | | - |
103 | | -final class UsersTest extends AbstractTest |
104 | | -{ |
105 | | - public function testAdminResource() |
106 | | - { |
107 | | - $response = $this->createClientWithCredentials()->request('GET', '/users'); |
108 | | - $this->assertResponseIsSuccessful(); |
109 | | - } |
110 | | - |
111 | | - public function testLoginAsUser() |
112 | | - { |
113 | | - $token = $this->getToken([ |
114 | | - 'username' => ' [email protected]', |
115 | | - 'password' => '$3cr3t', |
116 | | - ]); |
117 | | - |
118 | | - $response = $this->createClientWithCredentials($token)->request('GET', '/users'); |
119 | | - $this->assertJsonContains(['description' => 'Access Denied.']); |
120 | | - $this->assertResponseStatusCodeSame(403); |
121 | | - } |
122 | | -} |
123 | | -``` |
124 | | - |
125 | | -## API Test Assertions |
126 | | - |
127 | | -In addition to [the built-in ones](https://phpunit.readthedocs.io/en/latest/assertions.html), API Platform provides convenient PHPUnit assertions dedicated to API testing: |
128 | | - |
129 | | -```php |
130 | | -<?php |
131 | | -// api/tests/MyTest.php |
132 | | - |
133 | | -namespace App\Tests; |
134 | | - |
135 | | -use ApiPlatform\Symfony\Bundle\Test\ApiTestCase; |
136 | | - |
137 | | -class MyTest extends ApiTestCase |
138 | | -{ |
139 | | - public function testSomething(): void |
140 | | - { |
141 | | - // static::createClient()->request(...); |
142 | | - |
143 | | - // Asserts that the returned JSON is equal to the passed one |
144 | | - $this->assertJsonEquals(/* a JSON document as an array or as a string */); |
145 | | - |
146 | | - // Asserts that the returned JSON is a superset of the passed one |
147 | | - $this->assertJsonContains(/* a JSON document as an array or as a string */); |
148 | | - |
149 | | - // justinrainbow/json-schema must be installed to use the following assertions |
150 | | - |
151 | | - // Asserts that the returned JSON matches the passed JSON Schema |
152 | | - $this->assertMatchesJsonSchema(/* a JSON Schema as an array or as a string */); |
153 | | - |
154 | | - // Asserts that the returned JSON is validated by the JSON Schema generated for this resource by API Platform |
155 | | - |
156 | | - // For collections |
157 | | - $this->assertMatchesResourceCollectionJsonSchema(YourApiResource::class); |
158 | | - // And for items |
159 | | - $this->assertMatchesResourceItemJsonSchema(YourApiResource::class); |
160 | | - } |
161 | | -} |
162 | | -``` |
163 | | - |
164 | | -There is also a method to find the IRI matching a given resource and some criteria: |
165 | | - |
166 | | -```php |
167 | | -<?php |
168 | | -// api/tests/BooksTest.php |
169 | | - |
170 | | -namespace App\Tests; |
171 | | - |
172 | | -use ApiPlatform\Symfony\Bundle\Test\ApiTestCase; |
173 | | - |
174 | | -class BooksTest extends ApiTestCase |
175 | | -{ |
176 | | - public function testFindBook(): void |
177 | | - { |
178 | | - // Asserts that the returned JSON is equal to the passed one |
179 | | - $iri = $this->findIriBy(Book::class, ['isbn' => '9780451524935']); |
180 | | - static::createClient()->request('GET', $iri); |
181 | | - $this->assertResponseIsSuccessful(); |
182 | | - } |
183 | | -} |
184 | | -``` |
185 | | - |
186 | | -## HTTP Test Assertions |
187 | | - |
188 | | -All test assertions provided by Symfony (assertions for status codes, headers, cookies, XML documents...) can be used out of the box with the API Platform test client: |
189 | | - |
190 | | -```php |
191 | | -<?php |
192 | | -// api/tests/BooksTest.php |
193 | | - |
194 | | -namespace App\Tests; |
195 | | - |
196 | | -use ApiPlatform\Symfony\Bundle\Test\ApiTestCase; |
197 | | - |
198 | | -class BooksTest extends ApiTestCase |
199 | | -{ |
200 | | - public function testGetCollection(): void |
201 | | - { |
202 | | - static::createClient()->request('GET', '/books'); |
203 | | - |
204 | | - $this->assertResponseIsSuccessful(); |
205 | | - $this->assertResponseHeaderSame('content-type', 'application/ld+json; charset=utf-8'); |
206 | | - } |
207 | | -} |
208 | | -``` |
209 | | - |
210 | | -[Check out the dedicated Symfony documentation entry](https://symfony.com/doc/current/testing/functional_tests_assertions.html). |
| 12 | +- If you are using API Platform with Symfony, refer to the [Testing the API with Symfony](/symfony/testing.md) documentation. |
| 13 | +- If you are using API Platform with Laravel, refer to the [Testing the API with Laravel](/laravel/testing.md) documentation. |
0 commit comments