---
title: "Guide du developpeur"
weight: 15
description: "Comprendre l'organisation de capTests et l'integrer a un projet : ecrire les cas, relier les tests automatiques, remonter les resultats, dater une version."
---
# 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
| Notion | Ce que c'est | Page de détail |
|--------|--------------|----------------|
| Projet | Un logiciel suivi. Porte un préfixe de référence (ex. `SI`). | [Administration](/captests/administration) |
| Cas (point de test) | Une chose à vérifier. Reçoit une **référence stable** (ex. `SI-001`) qui ne change jamais. | [Cas de test](/captests/cas-de-test) |
| Version | Une livraison (ex. `2.0.65.304`). Ouvre une **campagne** où tous les points repassent "non testé". | [Couverture automatique](/captests/couverture-automatique) |
| Plateforme | Cible d'un point : mobile / tablette / desktop. Permet de releaser appareil par appareil. | [Cas de test](/captests/cas-de-test) |
| Badge de couverture | État d'un point pour une version : Couvert, Partiel, Régression, En attente CI, Ignoré, Non couvert, Manuel. | [Couverture automatique](/captests/couverture-automatique) |
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](/captests/premiers-pas)
et [Rôles et permissions](/captests/roles-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
```mermaid
flowchart LR
A["Ecrire / tenir
les cas (refs)"] --> B["Relier les tests
automatiques"]
B --> C["Lancer la CI
(Playwright / PHPUnit)"]
C --> D["Remonter les resultats
(un run par source)"]
D --> E["Couverture
recalculee par version"]
E --> F["Si tout vert :
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-[` sur le test, reporter `captest-playwright-reporter`
(`reporters/playwright/`).
- **PHPUnit** : attribut `#[Group('][')]`, 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](/captests/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](/captests/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](/captests/cas-de-test) -- créer et organiser les points.
- [Couverture automatique](/captests/couverture-automatique) -- les badges et la
synthèse par version.
- [Automatisation](/captests/automatisation) -- le branchement CI / agent IA au
niveau fonctionnel.
- [Todolist et verdicts](/captests/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/`.
]