Le cliquet de couverture

English · Type : procédure · Public : contributeur · Contexte : dépôt du moteur · Statut : prête · S'applique depuis : 4.2.3

Les seuils de couverture de vite.config.ts ne font que monter. Deux vérifications les tiennent : Vitest échoue quand les tests atteignent moins qu'un seuil, et le cliquet échoue quand un seuil traîne trois points ou plus derrière ce que les tests atteignent. Cette page dit quoi faire quand l'une ou l'autre est rouge.

Ce que vous obtenez

Un job coverage de nouveau vert : chaque seuil atteint, et chaque seuil à moins de trois points de ce que mesurent les tests.

Contexte et versions

Le dépôt du moteur. Les seuils datent de la 4.1.0 « Clarity » (le niveau mesuré alors) ; le cliquet, tools/coverage-ratchet.ts, de la 4.1.3 ; ses annotations GitHub de la 4.1.9.

Ce qui est mesuré : la couverture V8 de src/**/*.ts (pas les *.d.ts), bridge/src/**/*.ts et studio-server/src/**/*.ts, par la suite unitaire et les tests d'assets (npm run test:coverage). Les seuils en 4.4.0 :

Les valeurs exactes sont dans vite.config.ts, test.coverage.thresholds, avec la raison de chaque seuil sous 100 écrite à côté.

Limite · lines-not-proof La couverture compte les lignes et les branches exécutées, pas les résultats vérifiés. Les parties de src/ propres au navigateur (l'interface du joueur et celle du Studio) sont couvertes par les e2e, pas par cette mesure ; savoir si les tests distinguent un bon résultat d'un mauvais, c'est la question des Tests de mutation.

Prérequis

Un dépôt préparé avec Python et ses modules d'image (Préparer son poste de développement) : les tests d'assets tournent eux aussi sous couverture.

Où lancer les commandes

Dans le dépôt du moteur, sur votre machine. La CI lance la même chose dans son job coverage.

Étapes

1. Mesurez.

   # dans le dépôt du moteur
   npm run test:coverage
   

   Elle lance la suite unitaire sous couverture et écrit .cache/coverage/ (un résumé texte, coverage-summary.json, un rapport HTML dans .cache/coverage/index.html). Vitest échoue ici quand un seuil n'est pas atteint, en nommant le fichier et la mesure.

2. Un seuil non atteint (les tests atteignent moins que lui) : votre changement a retiré des tests ou ajouté du code qu'aucun test n'exécute. Ajoutez les tests ; ouvrez .cache/coverage/index.html pour voir les lignes et les branches non exécutées. On n'abaisse jamais un seuil pour laisser passer un changement.

3. Lisez le cliquet.

   # dans le dépôt du moteur, après test:coverage
   npx tsx tools/coverage-ratchet.ts            # avertit
   npx tsx tools/coverage-ratchet.ts --strict   # échoue, comme sur main
   

   Chaque ligne ⚠ <portée> <mesure>: floor <n>, measured <m> est un seuil trois points ou plus sous ce que les tests atteignent. La fin dit ✔ every coverage floor is within three points of what the tests reach, ou le nombre de seuils à relever.

4. Relevez les seuils qu'il nomme dans vite.config.ts (test.coverage.thresholds), à une valeur égale ou un peu inférieure à la mesure, et committez-les avec le changement qui les a mérités. vite.config.ts est un fichier que relit le mainteneur (CODEOWNERS).

Limite · ratchet-scope Le cliquet ne lit que les seuils qui existent : un fichier sans seuil propre n'est tenu que par les seuils globaux. Un seuil par fichier s'applique quand le résumé contient ce fichier.

Résultat attendu, et comment le vérifier

npm run test:coverage passe et npx tsx tools/coverage-ratchet.ts --strict sort avec 0. Dans la CI, le job coverage est vert, sans annotation « coverage ratchet ».

Erreurs fréquentes

Fichiers ou données modifiés

vite.config.ts (les seuils) ; la mesure n'écrit que dans .cache/coverage/.

Revenir en arrière

Un seuil relevé trop haut fait échouer l'exécution suivante : redescendez-le à ce que les tests atteignent (avec la raison dans la pull request), car un seuil au-dessus de la mesure est un build rouge, pas une promesse.

Références

• tools/coverage-ratchet.ts, vite.config.ts.
• Quels tests tournent quand, La CI expliquée, Tests de mutation.

Modifier la source de cette page · Signaler une erreur