Laravel Guardrails

Discipline de test Pest

Les fonctionnalités livrées non testées — ou « testées » avec des suites trop mockées qui vérifient les détails d'implémentation — plantent silencieusement en production et pourrissent à chaque refactorisation. Cette compétence vous fait écrire des tests Pest 3/4 qui prouvent le comportement, couvrent les chemins d'échec et d'autorisation, et survivent aux refactorisations.

Le piège

Deux modes de défaillance, tous deux coûteux :

1. Pas de tests / tests uniquement positifs. La fonctionnalité fonctionne dans la démo, puis en production un invité accède au point de terminaison, un locataire lit les données d'un autre locataire, une lacune de validation laisse entrer des déchets, ou une 404 devient une 500. Les failles d'autorisation (chemins 403/404 jamais vérifiés) sont ainsi que les fuites de données arrivent en production.
2. Tests fragiles et trop mockés. Vous mockez votre propre UserRepository/service avec shouldReceive('save')->once(), donc le test passe même si la vraie requête est erronée, et il explose dès que quelqu'un renomme une méthode. La suite est verte, donne une fausse confiance, et est supprimée par frustration lors de la prochaine refactorisation — vous laissant revenir au mode 1.

La solution est la même discipline dans les deux cas : fausser les frontières que vous ne possédez pas, exécuter le code que vous possédez, et vérifier les résultats observables (lignes DB, statut HTTP, jobs/mails dispatchés) — y compris les résultats d'échec et d'autorisation.

Règles

1. Écrire le test avec la fonctionnalité, pas « plus tard ». Un changement de contrôleur/job/commande/politique est incomplet tant qu'il n'a pas un test Pest. Ne signalez jamais une fonctionnalité comme terminée sans un test correspondant vérifiant son comportement.
2. Utiliser les idiomes Pest. Définissez les cas avec it('...') ou test('...') ; vérifiez avec le fluide expect(...) ; partagez la configuration avec beforeEach(). N'écrivez pas class FooTest extends TestCase à la PHPUnit sauf si le fichier utilise déjà ce style.
3. Choisissez le bon type. Comportement HTTP/end-to-end → Test de fonctionnalité (démarre le framework, accède aux routes via $this->get/post/...). Logique pure sans framework/DB → Test unitaire. Par défaut, choisissez un test de fonctionnalité en cas de doute — il attrape plus de problèmes.
4. Réinitialisez la base de données avec un trait, via uses(). Appliquez RefreshDatabase (enveloppé dans une transaction) ou LazilyRefreshDatabase (migre uniquement lorsqu'un test touche la DB) dans tests/Pest.php pour tout le répertoire Feature, ou uses(RefreshDatabase::class) en haut d'un fichier. NE laissez JAMAIS les tests DB dépendre d'un état résiduel.
5. Construisez les données avec des usines, jamais des insertions à la main. Utilisez User::factory()->create() / ->make() et les usines de relations. Les DB::table()->insert([...]) ou new Model([...])->save() faits à la main dans les tests sont fragiles et ignorent les casts/valeurs par défaut — bannissez-les.
6. Dédoublez avec des jeux de données, pas du copier-coller. Lorsque la même vérification s'exécute sur plusieurs entrées (charges utiles valides/invalides, matrices de rôles), utilisez ->with([...]) (inline ou un jeu de données nommé dans tests/Datasets/) au lieu de N tests quasi identiques.
7. Faussez les frontières que vous ne possédez pas. Pour tout ce qui est externe ou asynchrone, utilisez les fausses façade avant l'action : Http::fake(), Queue::fake(), Bus::fake(), Mail::fake(), Notification::fake(), Event::fake(), Storage::fake(). Pour le temps, utilisez $this->travel(...), $this->travelTo(...), ou $this->freezeTime() — ne vérifiez jamais contre un now() non figé.
8. NE mockez PAS vos propres modèles/services jusqu'à les rendre insignifiants. Évitez Mockery::mock(MyService::class)->shouldReceive(...) et Model::shouldReceive(...) pour le code testé. Laissez le vrai code s'exécuter contre la DB de test et les frontières fausses. Mockez votre propre classe uniquement à une véritable couture que vous n'exercez pas (par exemple, un wrapper SDK tiers lent).
9. Vérifiez les résultats, pas les internes. Préférez assertDatabaseHas / assertDatabaseMissing / assertModelExists, assertStatus / assertOk / assertCreated, assertJson / assertJsonPath, assertRedirect, Mail::assertSent, Notification::assertSentTo, Queue::assertPushed, Bus::assertDispatched, Storage::disk()->assertExists. Ne vérifiez pas « la méthode X a été appelée une fois » comme proxy du comportement.
10. Testez toujours le chemin d'échec ET l'autorisation. Chaque point de terminaison/action nécessite, au minimum : le chemin heureux, un chemin de validation/échec, et les chemins d'auth — invité → 401/redirection, mauvais utilisateur/rôle → 403, ressource manquante/étrangère → 404. Pour toute fonctionnalité sensible à la sécurité, ajoutez un test explicite « un autre utilisateur ne peut pas accéder/modifier cela ». C'est non-négociable pour tout ce qui touche à la propriété ou à la location.
11. Ajoutez des tests d'architecture comme garde-fous globaux à faible coût. Gardez un fichier tests/Arch.php (ou des cas d'arch dans Pest.php) avec les préréglages qui conviennent : arch()->preset()->php() (bannit la sortie de débogage die/var_dump/dd et les fonctions PHP obsolètes), arch()->preset()->security() (bannit eval, extract, unserialize, le hachage faible/md5/sha1, l'aléatoire non sécurisé, etc.), et arch()->preset()->laravel() (impose les conventions Laravel — y compris pas de env() en dehors de config). Ajoutez des invariants de projet comme arch('controllers')->expect('App\Http\Controllers')->toExtend('App\Http\Controllers\Controller').
12. Un comportement par test, nom descriptif. it('bloque les invités du tableau de bord'), pas it('fonctionne'). Si un nom de test a besoin d'un « et », divisez-le.
13. Couverture de porte dans CI. Exécutez ./vendor/bin/pest --coverage --min=NN pour imposer un minimum, et ./vendor/bin/pest --type-coverage (nécessite le plugin type-coverage) pour imposer des signatures typées. Traitez les nouvelles lignes non testées comme un défaut.
14. Browser/E2E avec parcimonie (Pest 4). Pest 4 propose des tests navigateur via visit('/')->...->assertSee(...) (basé sur Playwright). Réservez-le pour les flux full-stack/JS véritables ; ne réimplémentez pas les vérifications de couche HTTP comme des tests navigateur lents.

Bon vs mauvais

// tests/Feature/UpdatePostTest.php

use App\Models\Post;
use App\Models\User;

// ❌ trop mocké : teste qu'une méthode a été appelée, pas ce qui s'est passé.
//    Passe même si le mauvais article est mis à jour ou si l'auth est absente.
it('met à jour un article', function () {
    $service = Mockery::mock(App\Services\PostService::class);
    $service->shouldReceive('update')->once()->andReturnTrue();
    $this->app->instance(App\Services\PostService::class, $service);

    $this->put('/posts/1', ['title' => 'Nouveau'])->assertOk();
});

// ✅ exécute le vrai code contre la DB de test ; vérifie le résultat ET l'authz.
use App\Models\Post;
use App\Models\User;

it('laisse le propriétaire mettre à jour son article', function () {
    $owner = User::factory()->create();
    $post  = Post::factory()->for($owner)->create(['title' => 'Ancien']);

    $this->actingAs($owner)
        ->put("/posts/{$post->id}", ['title' => 'Nouveau'])
        ->assertRedirect();

    $this->assertDatabaseHas('posts', ['id' => $post->id, 'title' => 'Nouveau']);
});

it('interdit à un non-propriétaire de mettre à jour l\'article', function () {
    $post     = Post::factory()->create(['title' => 'Ancien']);
    $attacker = User::factory()->create();

    $this->actingAs($attacker)
        ->put("/posts/{$post->id}", ['title' => 'Piraté'])
        ->assertForbidden(); // 403

    $this->assertDatabaseHas('posts', ['id' => $post->id, 'title' => 'Ancien']);
});

it('bloque les invités', function () {
    $post = Post::factory()->create();

    $this->put("/posts/{$post->id}", ['title' => 'Nouveau'])
        ->assertRedirect('/login'); // ou assertUnauthorized() pour une API
});

// ❌ touche le vrai réseau (instable, lent, peut fuiter des clés) ; ne vérifie rien d'utile.
it('notifie slack', function () {
    $resp = (new App\Services\Slack)->ping('déploiement ok');
    expect($resp)->toBeArray();
});

// ✅ fausse la frontière que vous ne possédez pas ; vérifie la requête envoyée.
use Illuminate\Support\Facades\Http;

it('envoie le message de déploiement à slack', function () {
    Http::fake(['hooks.slack.com/*' => Http::response(['ok' => true])]);

    (new App\Services\Slack)->ping('déploiement ok');

    Http::assertSent(fn ($request) =>
        $request->url() === 'https://hooks.slack.com/services/T/B/x'
        && $request['text'] === 'déploiement ok'
    );
});

// ❌ tests de validation quasi identiques copiés-collés.
it('rejette un email vide', function () {
    $this->post('/register', ['email' => ''])->assertSessionHasErrors('email');
});
it('rejette un mauvais email', function () {
    $this->post('/register', ['email' => 'nope'])->assertSessionHasErrors('email');
});

// ✅ un seul test, piloté par un jeu de données.
it('rejette les emails invalides', function (string $email) {
    $this->post('/register', ['email' => $email])
        ->assertSessionHasErrors('email');
})->with([
    'vide'        => '',
    'pas d@'      => 'nope',
    'pas de domaine' => 'a@',
]);

// ✅ frontières asynchrones + temporelles fausses ; vérifie le dispatch et l'effet secondaire.
use App\Jobs\SendReminder;
use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Queue;

it('met en file d\'attente un rappel et accueille l\'utilisateur lors de l\'inscription', function () {
    Queue::fake();
    Mail::fake();
    $this->freezeTime();

    $this->post('/register', [
        'name' => 'Ada', 'email' => '[email protected]', 'password' => 'mot-de-passe-secret',
    ])->assertRedirect();

    Queue::assertPushed(SendReminder::class);
    Mail::assertSent(WelcomeMail::class, fn ($m) => $m->hasTo('[email protected]'));
    $this->assertDatabaseHas('users', ['email' => '[email protected]']);
});

// tests/Arch.php — ✅ garde-fous globaux à faible coût
arch()->preset()->php();        // bannit la sortie de débogage die/var_dump/dd + fonctions PHP obsolètes
arch()->preset()->security();   // bannit eval, extract, unserialize, md5/sha1, aléatoire faible, etc.
arch()->preset()->laravel();    // impose les conventions Laravel, incl. pas de env() en dehors de config

arch('les contrôleurs étendent le contrôleur de base')
    ->expect('App\Http\Controllers')
    ->toExtend('App\Http\Controllers\Controller');

arch('les modèles vivent dans le bon espace de noms')
    ->expect('App\Models')
    ->toExtend('Illuminate\Database\Eloquent\Model');

Comment vérifier

Exécutez ces commandes avant de déclarer une fonctionnalité + ses tests comme terminés :

# 1. Toute la suite doit être verte.
./vendor/bin/pest

# 2. Exécutez uniquement le(s) nouveau(x)/modifié(s) fichier(s) pendant l'itération.
./vendor/bin/pest tests/Feature/UpdatePostTest.php

# 3. Imposez un seuil de couverture (nécessite Xdebug ou PCOV).
./vendor/bin/pest --coverage --min=80

# 4. Couverture des types (nécessite pestphp/pest-plugin-type-coverage).
./vendor/bin/pest --type-coverage --min=100

# 5. Le style reste propre.
./vendor/bin/pint --test

Ensuite, auditez que vous N'AVEZ PAS réintroduit le piège :

# Couverture d'authz : chaque test de fonctionnalité protégé doit vérifier un chemin 401/403/404.
grep -rEn "assertForbidden|assertUnauthorized|assertNotFound|->assertStatus\((401|403|404)\)" tests/

# Odeur de sur-mockage : mocker vos propres classes d'application est un drapeau rouge — examinez chaque occurrence.
grep -rEn "Mockery::|->shouldReceive\(|::partialMock\(|::spy\(" tests/

# Insertions à la main au lieu d'usines — remplacez par ->factory().
grep -rEn "DB::table\(.*\)->insert|new App\\\\Models" tests/

# Les frontières externes doivent être fausses — confirmez que les fausses existent là où le code appelle de l'extérieur.
grep -rEn "Http::fake|Queue::fake|Bus::fake|Mail::fake|Notification::fake|Storage::fake|Event::fake" tests/

# Les préréglages d'arch sécurité + php (les garde-fous globaux à faible coût) doivent être présents quelque part.
grep -rEn "preset\(\\)->(security|php|laravel)\(\\)" tests/

Vérifiez dans les tests, pas seulement dans le code : pour chaque nouveau point de terminaison, confirmez qu'il y a (a) une vérification de résultat du chemin heureux (assertDatabaseHas/assertOk/assertJsonPath), (b) au moins une vérification d'échec/validation, et (c) les vérifications d'autorisation invité + mauvais utilisateur. Si l'un manque, la fonctionnalité n'est pas terminée.

Quand il est acceptable de déroger à la règle

• Mocker votre propre code à une véritable couture externe. Un wrapper mince autour d'un SDK tiers payant (SMS, passerelle de paiement) que vous ne pouvez pas fausser au niveau HTTP est une cible légitime pour Mockery — vous isolez leur dépendance, vous ne faussez pas le comportement testé.
• Tester unitairement une logique pure sans base de données. Les objets de valeur, formatteurs et calculateurs n'ont besoin ni de RefreshDatabase ni d'usines — instanciez-les directement et utilisez expect() pour le résultat ; c'est plus rapide et correct.
• make() plutôt que create() lorsqu'un test ne persiste jamais — User::factory()->make() évite une écriture DB pour les vérifications de logique pure.
• Seuils de couverture plus bas sur le code hérité. Fixez un --min réaliste et augmentez-le progressivement plutôt que de bloquer tout travail ; ne laissez jamais « 100% ou rien » devenir une excuse pour livrer zéro test.
• Tests navigateur pour les flux vraiment pilotés par JS (interactions Livewire/Inertia/Vue, sélecteurs de fichiers) — là, visit() est le bon outil, pas une exagération.

Références

• Pest — Écrire des tests, expectations, hooks : https://pestphp.com/docs/writing-tests
• Pest — Jeux de données : https://pestphp.com/docs/datasets
• Pest — Tests d'architecture & préréglages (security, laravel, toExtend) : https://pestphp.com/docs/arch-testing
• Pest — Couverture & --min : https://pestphp.com/docs/coverage
• Pest — Plugin de couverture des types : https://pestphp.com/docs/type-coverage
• Pest v4 — Tests navigateur (visit(), régression visuelle) : https://pestphp.com/docs/browser-testing
• Laravel — Tests HTTP (vérifications de statut/JSON/redirection) : https://laravel.com/docs/testing
• Laravel — Tests de base de données (RefreshDatabase, usines, assertDatabaseHas) : https://laravel.com/docs/database-testing
• Laravel — Mocking & fausses façade (Http, Queue, Bus, Mail, Notification, Event, Storage, temps) : https://laravel.com/docs/mocking