Contrats et vérification fr FR

Résumé : Cette page décrit la stratégie de vérification de StartER, basée sur le Contract-Driven Development pour l'API et React Testing Library pour l'interface.

La vérification à l'ère de l'IA

Dans StartER, les tests ne sont pas seulement là pour attraper des bugs ; ils servent de garde-fous pour l'IA et de documentation vivante. En définissant le comportement de l'API de manière déclarative dans le dossier tests/contracts/, vous fournissez une spécification claire que les agents IA peuvent utiliser pour générer et vérifier du code.

Tip

Lancez la suite complète avec :

npm run test

Intégration API : les contrats comme instructions pour l'IA

Au lieu d'écrire des fichiers de test impératifs, StartER utilise une approche basée sur des contrats.

Le dossier `tests/contracts/`

Ces fichiers sont la source unique de vérité pour votre API. Puisqu'ils exportent un objet TypeScript structuré, les agents IA peuvent les analyser pour comprendre exactement ce qu'ils doivent construire.

// Exemple de contrat pour la lecture d'un item
const contracts = {
  items: {
    read: {
      method: "get",
      path: "/api/items/1",
      cases: {
        success: {
          request: {},
          response: { status: 200, body: { id: 1, title: "Mon Item", user_id: 1 } },
        },
        not_found: {
          specialPath: "/api/items/NaN",
          request: {},
          response: { status: 404, body: {} },
        },
      }
    }
  }
};

Pourquoi c'est "AI-native" :

Riche en contexte : un agent IA lisant ce fichier connaît tous les cas d'erreur gérés (401, 404, 400) en un coup d'oeil.
Auto-correction : si l'IA génère une action qui renvoie une 404 alors qu'elle devrait renvoyer une 200, le test de contrat échouera. Vous pouvez alors redonner l'échec à l'IA pour une correction instantanée.
Consistance : le moteur de test (tests/express/contracts.test.ts) s'assure que chaque contrat est testé de la même manière, empêchant l'IA d'introduire des variations dans les tests.

Isolation et performance (SQLite)

Une force majeure de StartER réside dans l'utilisation de SQLite en mémoire pour la vérification :

Isolation parfaite : chaque test d'API démarre avec une base de données vide et indépendante créée en mémoire (:memory:). Un test ne peut jamais corrompre les données d'un autre test.
Respect du schéma : avant chaque scénario, le schéma (schema.sql) est appliqué. Vous testez donc toujours contre une structure de base de données réelle et à jour.
Vitesse : l'exécution est quasi instantanée car aucun accès disque n'est nécessaire.

Tests React

Les tests React se trouvent dans tests/react/ et se concentrent sur le comportement utilisateur.

React Testing Library : pour interagir avec le DOM de manière sémantique (getByRole, userEvent.click).
Mocks de données : le système de cache est simulé à l'aide des données du contrat, permettant de tester l'interface de manière isolée du réseau.

Exemple de test de composant :

it("should display an item", async () => {
  await renderWithStub({
    path: "/items/:id",
    Component: ItemShow,
    initialEntries: [`/items/${allItems[0].id}`],
    me: fooUser,
  });

  await screen.findByRole("heading", { level: 1, name: allItems[0].title });

  // Vérifie que le composant a "appelé" le contrat
  expectContractCall("items", "read", "success");
});

Bonnes pratiques pour la vérification IA

Contrat d'abord : mettez toujours à jour les contrats dans le dossier tests/contracts/ avant de demander à l'IA d'implémenter la logique.
Données réalistes : utilisez des données proches de la réalité dans vos mocks pour que l'IA ait de bons exemples de structures de données.
Snake case : nommez vos scénarios en snake_case (ex : bad_request, unauthorized) pour la cohérence.