metalfrom.eu/README-CI.md

Qualité, tests et CI/CD

Le modèle en une phrase

Coolify redéploie sur webhook à chaque push (dev → dev.metalfrom.eu, main → metalfrom.eu). Rien ne s'interpose. La porte de qualité est donc locale, dans le hook pre-push.

git push ──▶ [pre-push : npm run check + test:e2e] ──▶ Forgejo ──▶ webhook ──▶ Coolify redeploy
                  ↑ 6 s + 22 s, bloquant

Deux granularités volontaires : check (6 s) tourne pendant qu'on code, les parcours Playwright (22 s) seulement au moment de pousser. Mettre l'e2e dans check ferait passer la boucle de 6 à 22 s pour un gain marginal — la plupart des régressions tombent déjà dans les tests unitaires.

Installation (une fois par clone)

npm install
npm run hooks:install                    # active .githooks/pre-push
pip install -r requirements-dev.txt

Commandes et temps mesurés

Commande	Ce que ça fait	Froid	Incrémental
npm run check	La porte : ESLint + tsc + Ruff + 620 tests	6 s	—
npm run check:sequential	Idem, en série (pour isoler un échec)	14 s	—
npm run test:mutation	Mutation, logique pure (352 mutants)	33 s	~5 s
npm run test:mutation:full	Mutation, toute l'API (2159 mutants)	~5 min	8 s
npm run test:e2e	85 parcours Playwright (dashboard admin)	26 s	—
npm run test:e2e:install	Récupère Chromium (clone neuf)	—	—
npm run check:full	check + e2e + audits + mutation complète	—	~1 min
npm run test:integration:full	SQL validé par un vrai PostgreSQL+PostGIS (exige Docker)	~30 s	—
npm run check:clean	Purge les caches ESLint / tsc	—	—

Où passe le temps

La commande de la boucle de développement, c'est npm run check : 6 s, tests compris. C'est elle qui tourne cent fois par jour, et elle est passée de 17 s à 6 s par trois mesures successives :

Levier	Gain
Les 5 vérifications en parallèle au lieu de && (elles sont indépendantes, et l'enchaînement npm coûtait 7 démarrages)	14 s → 6 s
Cache ESLint (--cache) et compilation incrémentale tsc	16 s → 14 s
Chemin critique restant : vitest 4,9 s, dont ~2 s de mise en place jsdom	—

La mutation n'est pas une commande de boucle courte :

• test:mutation (352 mutants) : 33 s à froid, ~5 s ensuite.
• test:mutation:full (1511 mutants) : 3 min 40 une seule fois, puis 12 s après une édition. Le fichier incrémental vit dans reports/, qui est gitignoré : un clone neuf paie donc le run complet une fois.

Ce qui a été essayé et rejeté sur mesure (les intuitions se sont trompées plus d'une fois — tout est re-mesurable) :

Piste	Résultat
Découper la mutation en 5 processus Stryker parallèles	262 s contre 235 s : chaque processus repaie son bac à sable et son dry-run. Retiré.
Monter concurrency de 6 à 16	Aucun effet : ~8,5 mutants/s dans tous les cas. Le débit est limité par l'orchestration mono-processus de Stryker, pas par le CPU.
Séparer les tests API / frontend en deux processus vitest	Aucun gain : 4,9 s dans les deux cas, jsdom domine.
Pool vitest threads sur la suite complète	18,8 s contre 3,5 s (jsdom pénalisé). Défaut conservé.
Pool vitest threads sur la config de mutation (sans jsdom)	Overhead d'amorçage 12 844 ms → 1 592 ms. Adopté.

Ce qui n'a délibérément pas été fait : réduire le périmètre muté. Descendre sous ~1500 mutants sur l'API reviendrait à ne plus mesurer grand-chose, et un score flatteur obtenu en retirant les mutants gênants est pire que pas de score. Le plancher de ~3 min à froid est celui de Stryker sur 1511 mutants, assumé.

Ce que couvrent les tests

Batterie	Où	Approche
Unitaires	apps/api/test/validate.test.js	Validation pure : bbox, limit/offset, coordonnées, années, recherche
Routes / intégration	publicRoutes*.test.js, adminRoutes*.test.js	fastify.inject() + faux pool. Gating d'auth, allowlists de colonnes, forme du SQL, transactions
Sécurité	adminAuth.test.js, rateLimit.test.js	JWT forgé, alg:none, expiration, anti-énumération, verrouillage de compte, plafonds de débit par IP et par jeton
Annulation	cancellation.test.js + apps/crawler/tests/test_cancellation.py	Les deux moitiés du protocole coopératif
Accessibilité	apps/web/test/a11y.test.js	axe-core + jsdom sur le HTML statique
Frontend	apps/web/test/pure.test.js	Filtrage, tri, échappement HTML
Méta	apps/api/test/harness.test.js	Vérifie le faux pool lui-même
Python	apps/geocoder/tests/, apps/crawler/tests/	Parseur de localisations, annulation
Parcours (e2e)	apps/admin/test/e2e/admin.spec.js	Playwright sur la VRAIE app Fastify + faux pool : connexion, recherche, édition, déblocage d'une localisation, annulation d'un traitement
a11y des vues rendues	apps/admin/test/e2e/a11y.spec.js	axe-core dans un vrai navigateur — contraste inclus, ce que jsdom ne sait pas calculer
Mutation	stryker*.config.json	82 % (logique pure) / 68 % (API complète)
Syntaxe SQL	apps/api/test/sqlSyntax.test.js	Chaque requête réellement émise est parsée avec la grammaire PostgreSQL — sans conteneur
Santé des services	apps/crawler/tests/test_health.py	Sondes du crawler et du geocoder : base, dépendances externes, fraîcheur des données
Intégration SQL	apps/api/test/integration/	Migrations réelles + PREPARE de chaque requête sur PostgreSQL+PostGIS : colonnes, types, PostGIS. Exige Docker, hors de check

Principe des tests

Aucun test ne monte de conteneur, ne compile, ni ne touche le réseau.

Deux choix structurants côté API :

1. Une app Fastify par fichier de test, pas par cas. buildServer() coûte 14 ms ; à raison d'une construction par it(), ces 14 ms étaient multipliés par des milliers d'exécutions en mutation. Les tests partagent une app et reprogramment un faux pool via pool.reset() (test/helpers/testApp.js).

2. Plafonds de débit paramétrables. Conséquence du point 1 : une app partagée accumule l'état du limiteur. Les valeurs réelles de production sont donc vérifiées séparément dans rateLimit.test.js, pour que cette paramétrisation ne crée pas d'angle mort sur une protection de sécurité.

Pourquoi deux profils de mutation

La mutation prouve qu'un test échoue quand le code casse — la couverture ne dit que « cette ligne a été exécutée ».

• test:mutation (validate.js, adminAuth.js) : 82 %. Logique pure, score interprétable, assez rapide pour être lancé souvent.
• test:mutation:full (+ adminRoutes.js, app.js) : 68 %. Les handlers de route plafonnent structurellement plus bas — beaucoup de mutants portent sur des messages de log ou des branches catch dont l'observable exact n'a pas d'importance. Utile en audit, pas en boucle courte.

Les seuils d'échec (70 % et 55 %) sont des cliquets anti-régression, pas des objectifs.

Ce que les survivants ont révélé

La liste des mutants survivants est la carte de ce qui n'est pas vérifié. Une passe dessus a montré que tous les filtres de /admin/api/bands étaient non testés (sept mutants survivants par drapeau booléen) — précisément ceux dont dépendent les filtres rapides du dashboard. Les tests écrits pour combler ce trou ont mis au jour un bug réel : genre n'était pas tronqué, contrairement aux autres champs de recherche.

Le score est passé de 64 % à 68 % en écrivant des tests, pas en retirant des mutants. reports/mutation-full.json contient le détail exploitable ; le script de tri utilisé est décrit dans l'historique Git.

Les parcours e2e

apps/admin/test/e2e/server.mjs reproduit la topologie de production : un serveur HTTP sert les fichiers statiques et proxifie /admin/* vers la VRAIE application Fastify (comme apps/admin/nginx.conf), avec un faux pool à la place de Postgres.

Sont donc réellement exercés : le routage Fastify, les cookies, le JWT, bcrypt, la validation des entrées et la génération SQL. Ne le sont pas : la validité du SQL pour Postgres et le comportement de PostGIS — affaire de tests d'intégration, pas de tests d'interface.

Démarrage ~1 s, aucun conteneur. Une session est enregistrée une fois (auth.setup.js) et partagée : sans ça, chacun des 53 scénarios repayait un aller-retour de connexion complet. 4 workers est l'optimum mesuré (8 et 12 sont plus lents — contention au démarrage des navigateurs).

Ce qui n'est pas couvert

• Règles a11y exigeant un moteur de rendu sur le site public : le test jsdom ne calcule pas les styles. Le dashboard admin, lui, est couvert par axe dans un vrai navigateur.
• migrate.js : s'exécute au démarrage du conteneur et appelle process.exit.
• Crawler et workers de géocodage : le parseur, l'annulation et les contrôles de santé sont couverts ; le reste est de l'I/O réseau et base.
• La sémantique SQL est désormais couverte par npm run test:integration:full, qui applique les migrations réelles puis fait PREPARE sur chaque requête : Postgres valide colonnes, types et fonctions PostGIS sans rien exécuter ni nécessiter de données. Elle exige Docker et reste donc hors de check.
• Ce qui n'est toujours pas couvert : le comportement à l'exécution sur des données réelles (résultats de PostGIS, performance des index).
• apps/web/site/pure.js est testé mais exclu de la mutation : il est chargé via fs + vm (comme le fait le navigateur), donc l'instrumentation Stryker ne l'atteindrait pas et afficherait un score faussement parfait.

Forgejo Actions

.forgejo/workflows/ci.yml existe mais ne tourne pas : aucun runner act_runner n'est enregistré sur le VPS. Le fichier est prêt si tu en ajoutes un. Il est volontairement informatif — il ne bloque pas le déploiement.