InMy.Live

JSON:API fournit de nombreuses options pour filtrer, trier et inclure des données supplémentaires dans les données demandées à l’aide de paramètres de requête. Tester cela peut être frustrant – mais dans ce didacticiel, je vais expliquer comment j’aborde le test de ces points de terminaison.

Prenons un exemple de point de terminaison où nous voulons obtenir une liste de projets, qui a le modèle de données suivant :

Project:
  attributes:
    id: string
    name: string
    description: text
    status: string (Enum: planning, in-progress, in-testing, done)
    active: boolean
  relationships:
    owner: BelongsTo (User)
    client: BelongsTo (Client)

Je ne montrerai pas le code du contrôleur, car c’est quelque peu subjectif. Cependant, nous devons renvoyer une ressource JSON: API dans une réponse JSON. Jetons un coup d’œil à la requête, qui sera basée sur mon précédent tutoriel sur Effective Eloquent.

final class FetchProjectsByUser
{
    public function handle(Builder $builder, string $user): Builder
    {
        return QueryBuilder::for(
            subject: $builder,
        )->allowedIncludes(
            includes: ['owner', 'client'],
        )->allowedFilters(
            filters: ['status', 'active'],
        )->where(
            'user_id',
            $user,
        )->getEloquentBuilder();
    }
}

À partir de là, nous pouvons commencer à tester le point de terminaison pour nous assurer que toutes les options sont disponibles. Nous voulons obtenir tous les projets, tous ceux qui sont actifs ou non, de différents statuts, et nous voulons nous assurer que nous pouvons inclure à la fois les informations du propriétaire et du client si cela est demandé. Mais qu’en est-il des tests de chemin malheureux?

Mon premier test lorsque je travaille avec des points de terminaison comme celui-ci consiste à m’assurer que les utilisateurs non authentifiés ne peuvent pas y accéder. Ces tests supposent que le contrôleur que nous voulons utiliser s’appelle IndexController.

it('returns the correct status code if unauthenticated', function (): void {
    getJson(
        uri: action(IndexController::class),
    )->assertStatus(
        status: Http::UNAUTHORIZED->value,
    );
});

Ce test est un ajout indispensable, garantissant que vous pouvez accéder ou non au point de terminaison selon que vous êtes connecté ou non. Nous pouvons ensuite tester pour nous assurer que nous obtenons le code de statut correct si nous sommes connectés.

it('returns the correct status code for users', function (): void {
    actingAs(User::factory()->create())->getJson(
        uri: action(IndexController::class),
    )->assertStatus(
        status: Http::OK->value,
    );
});

Ces tests plus simples sont souvent négligés et doivent être ajoutés pour vous assurer de bien faire les choses simples. Dans le passé, je les ai ignorés, en supposant que les choses fonctionneraient – seulement pour constater que je causais un problème avec un code que j’ai ajouté qui forçait 500 erreurs sur des points de terminaison spécifiques. Ensuite, nous pouvons passer à tester davantage de fonctionnalités spécifiques à JSON: API.

it('can fetch the projects client', function (): void {
    actingAs(User::factory()->create())->getJson(
        uri: action(IndexController::class, [
            'include' => 'client',
        ]),
    )->assertStatus(
        status: Http::OK->value,
    )->assertJson(fn (AssertableJson $json) => $json
        ->first(fn (AssertableJson $json) => $json
            ->has('relationships.client')
            ->etc()
        )
    );
});

Nous voulons tester que la relation existe ici, car nous n’obtiendrons pas d’informations complètes, y compris cette relation, juste assez pour savoir quoi demander pour des détails. Cela fait cependant partie de la conception de JSON:API.

L’étape suivante consiste à filtrer l’API, en veillant à ce que nous puissions récupérer des projets spécifiques en fonction des attributs filtrables que nous avons ajoutés à notre requête.

it('can filter to active projects only', function (): void {
    actingAs(User::factory()->create())->getJson(
        uri: action(IndexController::class, [
            'filter[active]' => true,
        ]),
    )->assertStatus(
        status: Http::OK->value,
    )->assertJson(fn (AssertableJson $json) => $json
        ->each(fn (AssertableJson $json) => $json
            ->where('attributes.active', true)
            ->etc()
        )
    );
});

Nous pouvons appliquer cette approche à tous les filtres que nous pourrions utiliser pour nos points de terminaison, permettant à toute personne travaillant avec notre API d’obtenir précisément les données dont elle a besoin.

Comment procédez-vous pour tester les points de terminaison de votre API ? Ceci est un guide simple pour tester les points de terminaison JSON:API dans Laravel à l’aide de pestPHP. Les principes peuvent être appliqués à tous les autres tests que vous devrez peut-être effectuer dans votre API.