Testez votre application

Introduction

L'API de test fonctionnel de BowPHP permet de tester vos API de manière fluide en utilisant des requêtes HTTP. Cette API est construite autour de PHPUnit, ce qui vous permet d'utiliser toute la puissance de ce framework pour effectuer des tests. Les principales opérations HTTP (GET, POST, PUT, DELETE, PATCH) sont couvertes, et il est possible d'ajouter des en-têtes ou des pièces jointes à vos requêtes.

Classe TestCase

La classe principale pour utiliser l'API de test est TestCase, qui étend la classe PHPUnitTestCase de PHPUnit. Elle fournit une interface simple pour envoyer des requêtes HTTP et vérifier les réponses.

Méthodes de la classe TestCase

Configuration

L'URL de base des appels HTTP provient, dans cet ordre :

1. La propriété protected ?string $url du test (si définie).
2. La variable d'environnement APP_URL.
3. Le fallback http://127.0.0.1:8080 (port par défaut de php bow run:server).

Pour personnaliser la résolution, surchargez la méthode protégée getBaseUrl(): string dans votre classe de test.

1. attach(array $attach)

Ajoute des fichiers / champs multipart à la prochaine requête. Les pièces jointes sont consommées après l'appel et ne fuient pas vers les requêtes suivantes du même test.

$test->attach([
  'file' => new \CURLFile('/path/to/file.jpg')
])->post('/upload');

2. withHeaders(array $headers)

Remplace les en-têtes appliqués à toutes les requêtes ultérieures du test.

$test->withHeaders([
  'Authorization' => 'Bearer token',
  'Content-Type'  => 'application/json',
]);

3. withHeader(string $key, string $value)

Ajoute (ou remplace) un seul en-tête.

$test->withHeader('X-Custom-Header', 'custom_value');

4. get(string $url, array $param = [])

Requête GET. Les paramètres sont ajoutés en query string.

$response = $test->get('/api/users', ['page' => 1]);

5. post(string $url, array $param = [])

Requête POST. Combinez avec attach() pour envoyer des fichiers.

$response = $test->post('/api/users', ['name' => 'John Doe']);

6. put(string $url, array $param = [])

Requête PUT.

$response = $test->put('/api/users/1', ['name' => 'John Updated']);

7. delete(string $url, array $param = [])

Vraie requête HTTP DELETE (plus de hack _method POST).

$response = $test->delete('/api/users/1');

8. patch(string $url, array $param = [])

Vraie requête HTTP PATCH.

$response = $test->patch('/api/users/1', ['name' => 'John Modified']);

9. head(string $url, array $param = [])

Requête HEAD : récupère uniquement les en-têtes, sans corps. Utile pour vérifier l'existence d'une ressource ou ses métadonnées.

$response = $test->head('/api/users/1');
$response->assertStatus(200);

10. options(string $url)

Requête OPTIONS — généralement utilisée pour le preflight CORS.

$response = $test->options('/api/users');

11. visit(string $method, string $url, array $params = [])

Dispatcher générique selon le verbe HTTP. Accepte get, post, put, patch, delete, head, options.

$response = $test->visit('patch', '/api/users/1', ['name' => 'X']);

Exemple complet d'utilisation

Voici un exemple complet qui montre comment configurer un test fonctionnel avec l'API de test :

use Bow\Testing\TestCase;

class UserApiTest extends TestCase
{
  protected ?string $url = 'http://localhost:8080';

  public function testCreateUser()
  {
    // Ajouter un en-tête d'autorisation
    $this->withHeader('Authorization', 'Bearer token');

    // Ajouter des données de test à envoyer dans la requête POST
    $data = [
      'name' => 'John Doe',
      'email' => 'john.doe@example.com'
    ];

    // Effectuer la requête POST
    $response = $this->post('/api/users', $data);

    // Vérifier que la réponse a le statut HTTP 201
    $response->assertStatus(201);
    $result = $response->toArray();

    // Vérifier que le nom de l'utilisateur créé est correct
    $this->assertEquals('John Doe', $result['name']);
  }

  public function testGetUser()
  {
    // Faire une requête GET pour récupérer un utilisateur
    $response = $this->get('/api/users/1');

    // Vérifier que la réponse a le statut HTTP 200
    $response->assertStatus(200);
    $result = $response->toArray();

    // Vérifier que l'ID de l'utilisateur est correct
    $this->assertEquals(1, $result['id']);
  }
}

Classe Response pour les tests fonctionnels

info

La classe Response permet de manipuler les réponses HTTP dans le cadre de tests fonctionnels avec BowPHP. Elle encapsule un objet de la classe HttpClientResponse et expose plusieurs méthodes pour effectuer des assertions sur la réponse.

Méthodes de la classe Response

1. assertJson(string $message = ''): Response

Vérifie que le contenu de la réponse est au format JSON. Si ce n'est pas le cas, un échec de test sera généré.

$response->assertJson("La réponse devrait être au format JSON");

2. assertExactJson(array $data, string $message = ''): Response

Vérifie que le contenu JSON de la réponse correspond exactement aux données spécifiées.

$response->assertExactJson([
  'name' => 'John Doe',
  'email' => 'john.doe@example.com'
], "La réponse JSON ne correspond pas aux données attendues.");

3. assertContainsExactText(string $data, string $message = ''): Response

Vérifie que le contenu de la réponse correspond exactement au texte donné.

$response->assertContainsExactText("Bienvenue, John Doe", "Le texte de la réponse ne correspond pas.");

4. assertHeader(string $header, string $message = ''): Response

Vérifie qu'un en-tête spécifique existe dans la réponse.

$response->assertHeader('Content-Type', "L'en-tête Content-Type est manquant.");

5. assertArray(string $message = ''): Response

Vérifie que le contenu de la réponse est un tableau.

$response->assertArray("La réponse devrait être un tableau.");

6. assertContentType(string $content_type, string $message = ''): Response

Vérifie que le type de contenu de la réponse correspond à celui spécifié.

$response->assertContentType('application/json', "Le type de contenu n'est pas 'application/json'.");

7. assertContentTypeJson(string $message = ''): Response

Vérifie que le type de contenu est application/json.

$response->assertContentTypeJson("Le type de contenu devrait être JSON.");

8. assertContentTypeText(string $message = ''): Response

Vérifie que le type de contenu est text/plain.

$response->assertContentTypeText("Le type de contenu devrait être text/plain.");

9. assertContentTypeHtml(string $message = ''): Response

Vérifie que le type de contenu est text/html.

$response->assertContentTypeHtml("Le type de contenu devrait être text/html.");

10. assertContentTypeXml(string $message = ''): Response

Vérifie que le type de contenu est text/xml.

$response->assertContentTypeXml("Le type de contenu devrait être text/xml.");

11. assertStatus(int $code, string $message = ''): Response

Vérifie que le code de statut HTTP de la réponse correspond à celui spécifié.

$response->assertStatus(200, "Le statut HTTP n'est pas 200.");

12. assertKeyExists(string $key, string $message = ''): Response

Vérifie qu'une clé existe dans le contenu JSON de la réponse.

$response->assertKeyExists('id', "La clé 'id' est manquante dans la réponse.");

13. assertKeyMatchValue(string|int $key, mixed $value, string $message = ''): Response

Vérifie qu'une clé spécifique dans le contenu JSON de la réponse correspond à une valeur spécifiée.

$response->assertKeyMatchValue('name', 'John Doe', "Le nom dans la réponse ne correspond pas.");

14. assertContains(string $text): Response

Vérifie que le contenu de la réponse contient une sous-chaîne spécifique.

$response->assertContains("Bienvenue", "Le texte 'Bienvenue' devrait être présent.");

15. getContent(): string

Récupère le contenu brut de la réponse.

$content = $response->getContent();

16. toArray(): array|object

Retourne le contenu de la réponse sous forme de tableau ou d'objet (si le contenu est JSON).

$data = $response->toArray();

17. __call(string $method, array $params = [])

Permet d'appeler dynamiquement les méthodes de l'objet HttpClientResponse encapsulé dans la réponse.

$response->getCode(); // Appelle getCode() sur HttpClientResponse

Exemple d'utilisation complète

Voici un exemple complet qui montre comment utiliser la classe Response pour tester une API :

use Bow\Testing\TestCase;

class UserApiTest extends TestCase
{
  public function testCreateUser()
  {
    // Effectuer une requête POST
    $data = [
      'name' => 'John Doe',
      'email' => 'john.doe@example.com'
    ];
    $response = $this->post('/api/users', $data);

    // Vérifier que la réponse a le statut 201
    $response->assertStatus(201, "Le statut HTTP devrait être 201");

    // Vérifier que le contenu est en JSON
    $response->assertJson("La réponse devrait être en JSON");

    // Vérifier que le nom dans la réponse est correct
    $response->assertKeyMatchValue('name', 'John Doe', "Le nom de l'utilisateur est incorrect.");
  }

  public function testGetUser()
  {
    // Effectuer une requête GET
    $response = $this->get('/api/users/1');

    // Vérifier que la réponse a le statut 200
    $response->assertStatus(200, "Le statut HTTP devrait être 200");

    // Vérifier que l'utilisateur existe
    $response->assertKeyExists('id', "L'ID de l'utilisateur devrait exister.");
  }
}

Références

Documentation complémentaire

Consultez la documentation officielle de PHPUnit pour plus d'informations sur les assertions et les fonctionnalités avancées.

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou sur directement sur le github.