Guide du développeur

Cette page est le point d'entrée pour un développeur qui découvre capTests et veut y brancher un projet. Elle synthétise l'organisation de la plate-forme et le flux de travail côté développement, et renvoie aux pages de détail pour chaque sujet.

Principe à garder en tête : capTests n'exécute pas les tests. Il centralise la liste des points à tester, ingère les résultats des tests automatiques (Playwright, PHPUnit) et des verdicts manuels, et calcule la couverture par version. Les tests, eux, tournent dans votre environnement / votre CI.

L'organisation en bref

La référence du cas est la clé de voûte : c'est elle qui relie un point à son test automatique. Tout le reste (intitulé, section, instructions) peut évoluer, la référence reste.

Comment y accéder

Trois portes d'entrée, selon l'usage :

• Console web (rôle Développeur) : créer et modifier les cas, créer les versions, relier les tests, lire la couverture. Voir Premiers pas et Rôles et permissions.
• API REST (/api/v1) : pour l'outillage et les reporters CI. L'ingestion des runs se fait sur POST /api/v1/projects/{id}/runs avec un jeton de service portant l'habilitation ci:ingest.
• Serveur MCP (POST /api/v1/mcp, JSON-RPC) : pour piloter la liste depuis un agent IA / l'IDE (créer des cas, relier des tests, remonter un run, créer/dater une version). Le guide dédié à l'agent décrit la connexion et chaque outil.

Le flux de travail type

flowchart LR
    A["Ecrire / tenir<br/>les cas (refs)"] --> B["Relier les tests<br/>automatiques"]
    B --> C["Lancer la CI<br/>(Playwright / PHPUnit)"]
    C --> D["Remonter les resultats<br/>(un run par source)"]
    D --> E["Couverture<br/>recalculee par version"]
    E --> F["Si tout vert :<br/>dater la version"]

Relier un test à un cas : deux mécanismes

capTests sait rapprocher un résultat de test du bon cas de deux façons. Les deux aboutissent au même calcul de couverture ; elles diffèrent par l'endroit où vit le lien test -> cas.

Mécanisme A -- le repère dans le test (canonique)

Le lien est porté par le test lui-même, via un repère dérivé de la référence du cas. Non invasif : on ajoute un tag/groupe, rien d'autre.

• Playwright : tag @TC-<ref> sur le test, reporter captest-playwright-reporter (reporters/playwright/).
• PHPUnit : attribut #[Group('<ref>')], extension CapTestExtension (reporters/phpunit/).

À la fin du run, le reporter collecte les tests repérés, en déduit le statut et POSTe le tout sur /api/v1/projects/{id}/runs. Configuration par variables d'environnement (CAPTEST_API_URL, CAPTEST_PROJECT, CAPTEST_VERSION, CAPTEST_TOKEN, CAPTEST_CI_REF). Détails dans les README de reporters/ et Automatisation.

À choisir quand on maîtrise les tests et qu'on accepte d'y poser un repère.

Mécanisme B -- la carte de couverture externe

Le lien vit dans un fichier à part, coverage-map.json, qui associe l'identité d'un test (nom de base du spec Playwright, ou nom de classe PHPUnit) à une ou plusieurs références de cas. Un reporter maison lit les fichiers de résultats déjà produits (JSON Playwright, JUnit PHPUnit), traduit chaque test en référence via la carte, puis appelle l'outil MCP report_run.

• Aucun tag dans les tests : utile quand on ne veut pas (ou ne peut pas) toucher les tests existants.
• Le mapping est centralisé et relisable d'un coup d'oeil.
• Exemple de référence complet et réutilisable : le module smartInterventions (test/captests/coverage-map.json + report-to-captests.mjs).

À choisir quand on préfère un lien externe non invasif, ou pour brancher une suite de tests existante sans la modifier.

Quel que soit le mécanisme, le repère envoyé doit être la référence du cas (SI-001), jamais le nom du test. Un nom de test non résolu ressort en orphan_refs côté serveur et ne met rien à jour.

Remonter les résultats

• Un run par source : chaque remontée est rattachée à une source (playwright ou phpunit) et à une version.
• Règle à connaître : une remontée REMPLACE les résultats de la paire (version, source) -- elle n'accumule pas. Il faut donc envoyer tout le résultat d'une source en un seul appel. Concrètement, si plusieurs suites PHPUnit tournent (intégration + unit + http), il faut fusionner les JUnit en un seul fichier avant de reporter, sinon seule la dernière suite survit.
• La couverture est recalculée à l'ingestion. Le badge dépend du résultat le plus récent sur la version : un test qui passe -> Couvert, qui échoue -> Régression.

Versions et date de sortie

• create_version est create-only : sur une version existante, elle la renvoie inchangée (elle ne met pas à jour released_at).
• update_version fait la mise à jour partielle (seuls les champs fournis changent), typiquement pour poser released_at en fin de campagne.
• Flux de release recommandé : lancer toutes les suites -> remonter chaque source (en un appel) -> si et seulement si tout est vert, poser released_at = aujourd'hui via update_version. smartInterventions automatise ce flux (test/captests/release.sh, cible make captests-release).

Vidéos de référence et d'échec

Un reporter peut publier une vidéo de référence (comportement attendu, envoyée une seule fois par cas et par plateforme) et une vidéo d'échec (rattachée à la version). Elles se retrouvent côte à côte sur la fiche du cas. Détail et geste type : Automatisation.

Pièges courants

• "En attente CI" : le cas a un test lié mais aucun run n'a encore remonté son résultat pour la version affichée. Un report le fait basculer en Couvert ou Régression. Vérifiez surtout que vous regardez la bonne version.
• Double remontée d'une même source : elle écrase la précédente (voir plus haut). Toujours un seul appel par source.
• coverage_level des liens "collant" : le niveau affiché dans les "Tests automatiques liés" d'un cas ne reflète pas forcément la dernière version. Pour l'état réel d'une version, fiez-vous à la synthèse de couverture.
• orphan_refs : une remontée dont le repère ne correspond à aucun cas. Signe d'un repère erroné (nom de test au lieu de la référence, ou référence inexistante sur le projet).

Pour aller plus loin

• Cas de test -- créer et organiser les points.
• Couverture automatique -- les badges et la synthèse par version.
• Automatisation -- le branchement CI / agent IA au niveau fonctionnel.
• Todolist et verdicts -- le quotidien des testeurs, utile à connaître côté dev.
• Spécification technique complète : docs/project.md du dépôt capTests.
• Reporters de référence : reporters/playwright/ et reporters/phpunit/.