klassci-test-e2e
Rejouer un test end-to-end KLASSCI supérieur sur un tenant réel. PRIORITÉ ABSOLUE = valider le fix ou la feature livré(e) dans la session courante (le code qu'on vient de merger/déployer), via logs av
SKILL.md.claude/skills/klassci-test-e2e/SKILL.md
GitHubKLASSCI Test E2E
Méthode courte et reproductible pour valider un flux réel sur tenant, sans s'arrêter au code ou aux tests unitaires.
Quand utiliser ce skill
- On vient de livrer un fix ou une feature et il faut prouver qu'il/elle marche en prod (cas n°1, par défaut)
- L'utilisateur demande une validation de bout en bout sur un tenant
- Il faut vérifier UI + données + endpoints + mutations réelles
- Le chantier touche BTS tronc commun, résultats, bulletins, inscriptions, orientation (scénario de régression, pas la cible imposée)
⚠️ Cible du test = ce qui a été livré dans la session, PAS le BTS TC par défaut
Le scénario BTS TC ci-dessous est un exemple de validation feature. La cible réelle de l'e2e est toujours le fix/feature de la session courante. Si la session a corrigé des routes, des colonnes, un écran présences, une page paie… c'est CELA qu'on valide d'abord et en priorité. Le BTS TC ne se rejoue que s'il a été touché OU comme régression rapide optionnelle.
Principes
- Toujours partir d'un cas réel, tenant + année + étudiant + inscription + classe.
- Prouver chaque étape par au moins deux sources : diagnostic CLI/API et écran navigateur.
- Ne pas conclure "c'est bon" sans données métiers réelles.
- En cas d'outil
klassci-clicassé sur un POST, basculer vers l'endpointapi/clisigné par token tenant. - Quand le moteur et l'UI divergent, corriger d'abord la source de vérité puis la projection.
- Tester le code DÉPLOYÉ : l'e2e valide le code en prod sur le tenant. Si tu viens de merger une feature,
déploie d'abord (
klassci pull <tenant> && klassci cache:clear <tenant>) sinon tu testes l'ancien code. - La cible n°1 est le fix/feature de la session, pas un parcours générique. Toujours commencer par l'Étape 0.
Étape 0 — Valider d'abord le fix / feature de la session courante (OBLIGATOIRE)
Avant tout scénario générique : lister ce qui a été livré cette session (diff des fichiers, commits, PRs) et dériver un test ciblé par changement. Ne JAMAIS conclure « validé » sur un fix sans avoir exécuté le chemin réel qui plantait.
0.1 — Inventaire de ce qui a été livré
git log --oneline origin/presentation -10 # commits de la session
git show --stat <sha> # fichiers touchés par chaque commit
Pour chaque changement, identifier : la route/page affectée, le rôle qui l'atteint, et le symptôme d'origine (404 ? 500 ? colonne inconnue ? indicateur à zéro ? variable indéfinie ?).
0.2 — Baseline logs AVANT (motif d'erreur d'origine)
# le wrapper n'a pas de cmd logs → API directe signée par token
$cfg=Get-Content "$HOME\.klassci\config.json"|ConvertFrom-Json; $t=$cfg.tenants.<tenant>
Invoke-RestMethod "$($t.url)/api/cli/logs?lines=200&level=error" -Headers @{Authorization="Bearer $($t.token)"}
Noter l'horodatage du dernier message d'erreur du motif visé.
0.3 — Déployer le fix, puis exercer le VRAI chemin authentifié
Déployer :
klassci pull <tenant> && klassci cache:clear <tenant>(route:clear + opcache reset).Se connecter en navigateur avec le rôle concerné (cf.
presentation-tenant-login.md: superadmin / Bonjour@123) et viser l'URL exacte du symptôme. Capturer le code HTTP réel (response.status()), pas seulement un screenshot.⚠️ Piège fondateur (404 routes) : un test non authentifié renvoie 302 (login) pour TOUTE route matchée comme non matchée → n'discrimine pas un 404 de route. Toujours tester authentifié pour un bug de route/permission. Un 200 + titre de page attendu = preuve ; un 404/500 = encore cassé.
Pour un endpoint qui renvoie du JSON (KPIs, data), le hit direct authentifié suffit à exécuter le code corrigé (ex :
/coordinateur/attendance-dashboard/dataexécutecalculateAttendanceStats).
0.4 — Baseline logs APRÈS
Re-tirer ?level=error et vérifier 0 occurrence du motif d'origine avec un horodatage postérieur au déploiement
(attention : une occurrence juste avant l'heure de déploiement est un faux positif).
0.5 — Cas particuliers de routes (leçon 2026-06-18)
Un whereNumber/contrainte sur une route peut être annulé par un doublon de la même méthode+URI défini
plus loin (la dernière définition écrase la position de la première dans la RouteCollection). Si une route
contrainte « ne prend pas » : grep -nE "<path>/\{" routes/web.php pour débusquer les doublons (cf.
feedback_duplicate_route_definitions). php artisan route:list local échoue souvent (DB requise) → la
preuve vient du tenant (hit authentifié + logs), pas de route:list local.
0.6 — Verdict par changement : pour CHAQUE fix/feature livré, statuer Validé en prod / Encore cassé /
Non exercé (raison). Ne pas masquer un changement non testé derrière un autre qui passe.
Deux CLI distincts (ne pas confondre)
| Outil | Quoi | Commandes |
|---|---|---|
klassci (binaire sur PATH) |
Ops tenant + KPIs | pull, cache:clear, migrate, permissions:fix, stats, students:list, students:show <id>, classes:list, inscriptions:list, payments:list, config:list |
klassci-cli.ps1 (repo, à la racine) |
Diagnostics BTS-TC / résultats riches | bts-tc:student-journey, bts-tc:diagnose, bts-tc:legacy-audit, bts-tc:results-consistency, bts-tc:orient, bts-tc:seed-academic-sample, resultats:diagnose, resultats:bulletin-consistency-diagnose, resultats:bts-annual-snapshot |
powershell -ExecutionPolicy Bypass -File ./klassci-cli.ps1 <cmd> — chaque sous-commande sans arg affiche son Usage:.
Le binaire klassci n'a pas de passthrough artisan : une commande custom serveur (ex: backfill) se lance
via le terminal cPanel (pas de SSH:22 vers LWS depuis la machine dev), ou via un endpoint /api/cli/* dédié.
⚡ EXEMPLE de validation feature — « le bulletin annuel prend-il bien le S1 du Tronc Commun ? » (validé Plan C 2026-06-10)
Ceci est un exemple de validation d'une feature précise (régression BTS TC). Ne le rejoue que si la session a touché le TC/bulletins, ou comme régression rapide optionnelle après l'Étape 0. Pour un autre fix/feature, applique la même rigueur (logs avant/après + chemin réel authentifié) sur SA route, pas sur celle-ci.
Pour valider en ~3 commandes que la chaîne TC→spécialité fonctionne sur le code déployé, sans construire
un cas from scratch : utilise un étudiant déjà orienté en modèle phases (source_model: phase_based,
le cas qui était cassé).
# 1. Trouver/confirmer un étudiant orienté phases (cas de réf presentation : 831, TC=classe 98 / spé=99, année 1)
powershell -ExecutionPolicy Bypass -File ./klassci-cli.ps1 bts-tc:student-journey presentation 831 1
# → vérifier source_model=phase_based + timeline tronc_commun(S1, classe TC) → specialisation(S2, classe spé)
# 2. Diagnostic résultats ANNUEL (exécute le code déployé)
powershell -ExecutionPolicy Bypass -File ./klassci-cli.ps1 resultats:diagnose presentation 831 99 1 annuel 1
# ✅ ATTENDU : class_map.semestre1_classe_id = la classe TC (98, pas la spé 99)
# + semestre1.moyenne lue depuis la classe TC, semestre2 depuis la spé
# + annual_state = "annual_complete" + annual_weighted = agrégat des DEUX semestres
# ❌ BUG (pré-Plan C) : S1 perdu, annuel incomplet ou ne reflétant que la spé
# 3. Cohérence fiche ↔ bulletin (snapshot vs bulletin officiel)
powershell -ExecutionPolicy Bypass -File ./klassci-cli.ps1 resultats:bulletin-consistency-diagnose presentation 831 99 1 annuel
# → has_divergence=false attendu. NB : si official_bulletin_exists=false (pas de bulletin persisté),
# la divergence ne peut pas se mesurer → la preuve vient de l'étape 2 (class_map + annual_complete).
Si aucun étudiant orienté phases n'existe (bts-tc:legacy-audit renvoie items vides), construire le cas :
bts-tc:orient <inscription_id> <target_classe_id> puis bts-tc:seed-academic-sample <inscription_id> <noteS1> <noteS2>
(écrit sur une inscription de test, jamais de migrate:fresh/wipe).
Backfill des bulletins annuels existants (post-correctif TC)
Quand un correctif change le calcul du bulletin (ex: Plan C), les bulletins déjà persistés gardent l'ancienne valeur jusqu'à régénération. La commande dédiée est idempotente et dry-run par défaut :
# DRY-RUN d'abord (read-only, recompute en transaction+rollback) — sur le serveur tenant via cPanel :
! cd ~/public_html/presentation && php artisan bts:tc-bulletins-backfill presentation --dry-run --annee=<id>
# Lire le compte de bulletins divergents. Si OK → run réel (sans --dry-run), backup mysqldump AVANT.
Ordre tenants (moins→plus critique) : presentation → hetec → rostan → ephrata → esbtp-yakro
→ esbtp-abidjan. JAMAIS prod Élite direct sans dry-run validé. Runbook : docs/runbooks/bts-tc-bulletins-backfill.md.
Pré-requis machine (tests + diagnostics locaux)
- MySQL local (XAMPP) doit tourner pour les diagnostics/tests qui tapent une DB locale — voir rule
klassci-local-test-suite.md(démarragemysqld, DBklassci_testing, lenteur RefreshDatabase, pièges seed). klassci_localpeut être vide de données métier → un dry-run/diagnostic local n'y trouvera rien ; les diagnostics réels se font contre le tenant (presentation) via le CLI signé par token.
Boucle E2E standard
1. Cadre du cas réel
Identifier :
- tenant, souvent
presentation annee_universitaire_idetudiant_idinscription_idclasse_source_idclasse_cible_idsi orientation
Commandes utiles :
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 bts-tc:student-journey presentation 831 1
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 bts-tc:diagnose presentation 831
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 resultats:diagnose presentation 831 99 1 annuel 1
2. Vérifier le parcours BTS TC
Valider :
- phase active
- timeline
tronc_commun -> specialisation - mapping de classes S1/S2
- cohérence année / niveau / filière
Si la sortie n'existe pas encore :
- créer la cible autorisée
- orienter l'inscription
Privilégier klassci-cli si le wrapper fonctionne. Sinon appeler api/cli directement avec le token tenant.
3. Vérifier la donnée académique réelle
Sans notes ni bulletins, le test académique n'est pas clos.
Checklist minimale :
- au moins une matière et une évaluation en S1 sur la classe TC
- au moins une matière et une évaluation en S2 sur la classe de spécialisation
- au moins une note par semestre
- bulletins S1 et S2 présents ou recalculables
Si besoin, utiliser un seed contrôlé côté API CLI sur une inscription de test, jamais un migrate:fresh ni un wipe.
4. Vérifier les résultats et l'annualisation
À prouver :
semestre1lit la classe TCsemestre2lit la classe de spécialisationannuelagrège S1 et S2 avec les poids configurés
Commandes utiles :
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 resultats:diagnose presentation 831 98 1 semestre1 1
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 resultats:diagnose presentation 831 99 1 semestre2 1
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 resultats:diagnose presentation 831 99 1 annuel 1
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 resultats:bulletin-consistency-diagnose presentation 831 98 1 semestre1
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 resultats:bulletin-consistency-diagnose presentation 831 99 1 semestre2
powershell -ExecutionPolicy Bypass -File .\klassci-cli.ps1 resultats:bulletin-consistency-diagnose presentation 831 99 1 annuel
5. Vérifier l'UI réelle
Utiliser npx dev-browser.
⚠️ Bypass LWS DDoS Protection (tenants prod hébergés chez LWS)
Les tenants prod (esbtp-yakro, esbtp-abidjan, ephrata, rostan) sont derrière LWS DDoS Protection qui détecte les navigateurs headless / fingerprint Playwright et retourne « Vérification échouée, accès non autorisé ». Pour passer le filtre :
- NE PAS utiliser
--headless(détection immédiate). - Spoof le User-Agent vers un Chrome standard via
page.setExtraHTTPHeadersAVANT legoto. - Utiliser
--browser <nom>pour persister la session (cookies/login).
Recette canonique inline (utilise heredoc, pas de fichier /tmp/*.js) :
npx dev-browser --browser test-yakro --timeout 90 <<'EOF' 2>&1 | tail -15
const page = await browser.getPage("main");
await page.setExtraHTTPHeaders({
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
});
await page.goto("https://esbtp-yakro.klassci.com/login", { waitUntil: "domcontentloaded", timeout: 25000 });
await page.fill('input[placeholder="Votre identifiant"]', "modestekouakou@esbtp-yakro.klassci.com");
await page.fill('input[placeholder="Votre mot de passe"]', "modestekouakou2025");
await page.click('button[type="submit"]');
await new Promise(r => setTimeout(r, 4000));
console.log("Logged in:", page.url());
// Navigation cible avec cache-bust pour bypass Varnish edge cache
await page.goto("https://esbtp-yakro.klassci.com/esbtp/resultats/etudiant/1287?periode=semestre2&classe_id=52&annee_universitaire_id=6&_t=" + Date.now(), { waitUntil: "domcontentloaded", timeout: 25000 });
await new Promise(r => setTimeout(r, 3000));
const path = await saveScreenshot(await page.screenshot({ fullPage: true }), "etudiant-1287-s2.png");
console.log("Screenshot:", path);
EOF
Logins tenants prod (testés) :
| Tenant | Password | |
|---|---|---|
| esbtp-yakro | modestekouakou@esbtp-yakro.klassci.com |
modestekouakou2025 |
Capturer + lire le screenshot : await saveScreenshot(await page.screenshot(), "nom.png") retourne le path. Lis ensuite via Read tool sur C:\Users\PAVILION\.dev-browser\tmp\nom.png.
Si le PDF reste vide / matières manquantes : croiser avec /api/cli/logs?lines=100&search=YOUR_TAG pour confirmer si le code patché s'exécute. Les Log::info n'apparaissent que si CLI logs sans filtre level — préférer Log::error('DEBUG_TAG …') pour debug rapide.
À contrôler au minimum :
etudiants.showinscriptions.showetudiants.indexinscriptions.indexresultats.etudiantsi concerné
Points BTS TC :
- badge de phase visible et lisible
- bloc
Parcours BTSprésent - historique S1/S2 correct
- moyenne annuelle affichée cohérente avec le diagnostic
- aucun fallback visuel trompeur
6. Déclarer le statut final
Ne dire "validé de bout en bout" que si :
- mutation métier réelle exécutée
- diagnostics BTS et résultats alignés
- UI alignée avec la donnée
- annualisation prouvée sur vraies données académiques
Sinon, conclure explicitement ce qui manque.
Pattern de sortie
Toujours rendre :
## Statut
Validé partiellement | Validé de bout en bout | Bloqué
## Preuves
- Cas réel : étudiant / inscription / classes / année
- Diagnostics : commandes + points saillants
- UI : pages vérifiées + écarts restants
## Gaps
- ce qui manque encore pour conclure
## Journal des contournements
| Je voulais | L'interface m'a obligé à | Raccourci à ajouter |
|---|---|---|
Journal des contournements — obligatoire en fin de test
Demande de Marcel (25 septembre 2026). Chaque fois que le test sort du chemin qu'un agent d'école suivrait, c'est un constat d'ergonomie, pas un détail technique à taire :
- appeler une fonction JavaScript parce que le bouton est caché ou inaccessible ;
- envoyer un formulaire par script parce qu'une fenêtre est sous le fond grisé ;
- deviner ou taper une adresse faute de lien dans le menu ;
- changer de module parce que l'écran renvoie ailleurs sans lien direct (« utilisez le Planning Général ») ;
- fermer des fenêtres surgissantes par script ;
- se connecter avec un autre rôle pour débloquer une étape ;
- recharger ou re-sélectionner pour qu'une liste se mette à jour.
Noter le contournement au moment où on le fait, puis le rendre en fin de test avec le raccourci qui le supprime (souvent un bouton ou un lien). Un agent d'école n'a pas la console : pour lui, chaque ligne du journal est un appel au support ou un abandon.
Exemple réel : « Ajouter un second professeur à une matière depuis la séance » → « ouvrir
openManageTeachersModal() en JavaScript, le bouton étant caché dès qu'un professeur est
associé » → « lien "+ Associer un autre enseignant" toujours visible ». Rapport de référence :
docs/audits/2026-09-25-audit-e2e-lmd/README.md.
Notes BTS TC
- Une inscription annuelle unique peut changer de phase sans changer d'identité.
- Le diagnostic n'est pas une preuve suffisante si aucune note réelle n'existe.
- Le bon ordre de preuve est : orientation réelle, seed ou données réelles, diagnostic semestre 1, diagnostic semestre 2, diagnostic annuel, vérification UI.