Que fait antijank ?
Mesurez le mouvement au lieu de le regarder. Une sonde s'exécute dans la page, lit la boîte, l'opacité effective et la position de défilement de chaque élément surveillé après chaque frame peint, et signale uniquement ce qui semble anormal. Vous obtenez quelques lignes de texte par interaction, et non des frames à inspecter.
Il rapporte des faits ("s'est déplacé de 44 pixels vers le bas en un seul frame"), et non une appréciation. Juger si une durée ou une courbe d'atténuation est correcte relève d'une revue séparée. Les défauts (à-coups, sauts, scintillements, poussées des voisins) passent en premier ; les changements qui n'ont simplement pas de transition (apparitions soudaines, échanges) sont listés à part, car l'instantané est souvent le bon choix.
Choisissez comment l'exécuter
<skill-dir> ci-dessous est le dossier de cette compétence (là où se trouve ce fichier).
A. Le navigateur que vous pilotez déjà : rien à installer. Si vous disposez d'un outil de navigation (Chrome DevTools MCP, Playwright MCP, ou un panneau navigateur ou une extension exécutant du JavaScript), chargez la sonde dans la page que vous testez. Cela conserve la session connectée de ce navigateur et n'ajoute rien au projet.
| Votre outil | Charger la sonde |
|---|---|
| Chrome DevTools MCP | evaluate_script avec sourcePath: "<skill-dir>/scripts/probe.js" et format: "script" |
| Playwright MCP | browser_run_code (browser_run_code_unsafe dans certaines versions) : async (page) => { await page.addScriptTag({ path: '<skill-dir>/scripts/probe.js' }) } |
Une page Playwright dans votre propre script | await page.addScriptTag({ path: '<skill-dir>/scripts/probe.js' }) |
| Un outil qui ne fait qu'évaluer du texte JavaScript | Évaluez le chargeur CDN ci-dessous. S'il est bloqué, évaluez le contenu de scripts/probe.min.js (42 Ko) à la place |
Le chargeur CDN récupère cette version exacte, et le hash d'intégrité force le navigateur à rejeter tout autre fichier :
await new Promise((ok, fail) => {
const s = document.createElement('script');
s.src = 'https://cdn.jsdelivr.net/npm/[email protected]/skills/antijank/scripts/probe.min.js';
s.integrity = 'sha384-gbt1FS2nRYbhwU3zqdkxuKbH6++BQeLIjkpVPLNNOwbu361o2lV0U6li+N879FDf';
s.crossOrigin = 'anonymous';
s.onload = ok;
s.onerror = () => fail(new Error('antijank : script CDN bloqué (Content-Security-Policy ou hors ligne)'));
document.head.append(s);
});
- Le chargement peut être répété sans risque sur la même page, et est nécessaire après chaque navigation.
- Une Content-Security-Policy stricte bloque les balises script, donc le chargeur CDN et
addScriptTagéchouent sur ces pages. L'évaluation du contenu du fichier via DevTools (evaluate_scriptavecsourcePath, ou le collage deprobe.min.js) n'est pas bloquée. - L'onglet doit être visible. Les navigateurs mettent en pause les frames dans les onglets et panneaux cachés, et la sonde refuse alors d'enregistrer (
status: hidden). - Ralentissez le CPU et activez le mouvement réduit avec le même outil. Dans DevTools MCP, appelez
emulateaveccpuThrottlingRate: 4, puis avecprefersReducedMotion: "reduce"; chaque appel remplace le précédent, et un appel vide réinitialise. Dans Playwright MCP, utilisezbrowser_emulate_mediaavecreducedMotion: "reduce", et pour le CPU, exécutezconst s = await page.context().newCDPSession(page); await s.send('Emulation.setCPUThrottlingRate', { rate: 4 }). - Pour enregistrer un chargement de page, la sonde doit s'exécuter avant les scripts de la page elle-même. Avec Playwright, ajoutez deux scripts d'initialisation, puis chargez la page et attendez le résultat :
Autres outils : utilisez le moteur d'exécution (B), qui enregistre le chargement par défaut.await page.addInitScript({ path: '<skill-dir>/scripts/probe.js' }); await page.addInitScript(() => antijank.start({ root: 'main' })); await page.goto(url); const result = await page.evaluate(() => antijank.wait());
B. Le moteur d'exécution (runner) : pour CI, chargements de page et la matrice complète en une seule commande. Il nécessite un shell, Node 22+ et Playwright dans le projet, et s'exécute en mode headless avec son propre Chromium, donc il est reproductible.
node <skill-dir>/scripts/run.mjs http://localhost:3000/inbox --click "button[aria-label='Composer']" --root main
node <skill-dir>/scripts/run.mjs http://localhost:3000 --steps steps.json --matrix
node <skill-dir>/scripts/run.mjs http://localhost:3000/settings # enregistre le chargement de la page
Le moteur d'exécution est limité à Chromium et fonctionne sur Node, quel que soit le projet. Si le projet n'a pas Playwright, le moteur le signale. Ajoutez-le avec le gestionnaire de paquets que le projet utilise déjà (regardez le fichier de verrouillage), puis téléchargez Chromium :
| Fichier de verrouillage | Ajouter Playwright | Télécharger Chromium |
|---|---|---|
pnpm-lock.yaml | pnpm add -D playwright | pnpm exec playwright install chromium |
yarn.lock | yarn add -D playwright | yarn playwright install chromium |
bun.lock / bun.lockb | bun add -d playwright | bunx playwright install chromium |
deno.lock | deno add npm:playwright (avec "nodeModulesDir": "auto" dans deno.json, pour que Node puisse le trouver) | deno run -A npm:playwright install chromium |
package-lock.json ou aucun | npm i -D playwright | npx playwright install chromium |
Demandez avant d'ajouter une dépendance au projet d'autrui ; l'option A n'en nécessite aucune. Exécutez node <skill-dir>/scripts/run.mjs --help pour toutes les options. Le moteur d'exécution désactive la Content-Security-Policy pour son propre navigateur.
Enregistrement
Lorsque l'action peut s'exécuter à l'intérieur de la page :
const result = await antijank.record(() => document.querySelector('#open').click(), { root: 'main' });
antijank.report(); // le rapport textuel
record attend la promesse de l'action avant de laisser l'enregistrement se stabiliser, donc une action asynchrone avec plusieurs étapes est enregistrée dans son intégralité.
Lorsque vous pilotez l'action depuis l'extérieur de la page (vrais clics et saisies via votre outil), maintenez l'enregistrement ouvert jusqu'à ce que vous ayez terminé :
antijank.start({ root: 'main', hold: true }); // 1. évaluer
// 2. cliquer, taper, attendre : autant d'étapes que l'interaction en nécessite
await antijank.release(); // 3. évaluer : se stabilise après la dernière étape, résout avec le résultat
antijank.report();
Survolez un élément avant de cliquer (DevTools MCP hover, Playwright MCP browser_hover), comme le ferait une personne, et démarrez l'enregistrement une seconde ou plus avant la première entrée. Un clic qui atterrit directement sur un élément déclenche ses effets de survol avec la pression, et quelque chose qui se met à jour tout seul (une horloge, un compteur en direct) a besoin de cette seconde pour être reconnu comme changeant déjà ; l'un ou l'autre peut sinon être confondu avec la réponse au clic. Le moteur d'exécution survole avant chaque clic.
Sans hold, l'enregistrement se stabilise dès que rien n'a bougé pendant environ 330 ms, ce qui peut tomber entre deux de vos étapes. Une attente (hold) qui n'est jamais libérée se termine par une erreur après holdTimeout (60 s par défaut). antijank.wait() résout avec le résultat une fois que l'enregistrement se termine ; antijank.stop() y met fin immédiatement.
Flux de travail
- Décidez quoi enregistrer. Une interaction par enregistrement : le déclencheur, la partie de la page qui doit réagir (
root), et ce que « terminé » signifie. Si le changement attend le réseau, passezwaitForavec un sélecteur qui existe une fois le changement arrivé, sinon l'enregistrement pourrait se stabiliser avant que quoi que ce soit ne se produise. - Utilisez une version de production lorsque vous le pouvez. Les versions de développement rejouent les effets (React StrictMode) et le rechargement à chaud ajoute des ralentissements, donc le mouvement peut différer de ce qui est livré. Si vous devez utiliser une version de développement, mentionnez-le dans votre rapport.
- Enregistrez et lisez le rapport. La sévérité est un point de départ : HIGH est presque toujours visible, LOW est souvent acceptable.
- Décidez quels résultats sont intentionnels. Les changements non animés sont listés à part des défauts. L'instantané est un choix valide pour les onglets, menus, infobulles et tout ce qui est fréquent ou piloté au clavier, donc n'ajoutez pas d'animation simplement pour effacer un résultat. Figez le comportement intentionnel avec une attente, ou marquez l'élément
data-antijank-ignore. - Écrivez des attentes sur ce qui devrait se produire (ci-dessous) et réexécutez avec elles. Cela transforme « ça a l'air bien » en un test pass/échec, et la même spécification peut se prémunir contre des régressions plus tard.
- Corrigez les défauts, puis réexécutez. Pour la vérification finale, enregistrez à vitesse normale, avec le CPU ralenti 4× et avec mouvement réduit (
--matrixdans le moteur d'exécution, ou les appels d'émulation dans A), car les bogues de timing (un premier frame lent qui mange une animation, une transformation tardive) apparaissent souvent uniquement lorsque le CPU est lent. - Rapportez avec des chiffres, par exemple « le compositeur se déplace de 245 à 562 pixels sur 170 ms, rien d'autre ne bouge de plus d'1 pixel, 0 résultat dans les trois conditions ».
Résultats et leurs causes habituelles
| Résultat | Signification | Cause habituelle et correctif |
|---|---|---|
blip | Est resté à une mauvaise position pendant 1 à 3 frames, puis est revenu | La transformation FLIP a été appliquée un frame en retard (après le rendu). Mesurez et définissez la transformation inverse dans le même frame que le changement de mise en page : layout effect, pas effect ou rAF |
jump (début) | Grand premier pas, puis mouvement fluide | L'animation démarre depuis la mauvaise origine, ou le premier frame est affiché avant que la valeur de départ ne soit définie |
jump (fin) / snap | Mouvement fluide, puis un à-coup à la fin | Mauvaise cible (mesure obsolète), ou la transformation est effacée avant que la mise en page ne corresponde |
jump (milieu) | Un frame bien plus grand que ses voisins | La mise en page a changé en cours d'animation (contenu arrivé), ou deux animations se relaient |
shift | Un élément au repos a bougé en un frame | Quelque chose au-dessus a été inséré, supprimé ou redimensionné sans animation. [cause: …] nomme une insertion, suppression ou déplacement ; [same frame: …] nomme un redimensionnement dans le même frame, une cause probable mais non prouvée. Animez la taille, réservez de l'espace, ou utilisez une superposition |
pop-in / pop-out | Apparu ou disparu à pleine opacité (non animé) | Correct si l'instantané est intentionnel. Sinon, il n'y a pas d'animation d'entrée ou de sortie, ou la transition d'entrée n'a jamais été exécutée car le style de départ n'a jamais été rendu (classe retirée dans le même frame qu'elle a été ajoutée) |
flash | Visible pendant seulement 1 à 2 frames | Un espace réservé ou un état obsolète rendu pendant un frame ; une alternance de rendu conditionnel |
flicker | L'opacité a baissé puis est remontée | Remontage (changement de clé), une réinitialisation d'état, ou une animation de sortie qui redémarre |
swap | Un élément remplacé par un autre sur place, sans fondu enchaîné (non animé) | Correct pour les onglets et les vues instantanées. Sinon, il manque une transition d'élément partagé ou hero |
reversal | A fait demi-tour en cours de déplacement | Deux animations qui pilotent une même valeur, ou un recentrage vers une ancienne position |
oscillation | La direction change de frame en frame | Deux scripts en conflit (ancrage de défilement contre un suiveur, une boucle ResizeObserver) |
resettle | A bougé à nouveau après s'être reposé | Correction après une mesure tardive (polices, images, contenu asynchrone) |
overshoot | Est allé bien au-delà de sa cible | Rebond du ressort plus important que prévu. Ignorez-le si le rebond est délibéré |
stretch | Texte mis à l'échelle de manière inégale | Animation d'échelle sur une boîte contenant du texte ; contre-échelle ses enfants ou animez la taille |
scroll-jump / scroll-fight | La position de défilement a sauté ou changé de direction | Défilement programmatique sans lissage, ancrage de défilement, ou deux suiveurs |
slow-frame | Un frame a pris 50 ms ou plus | Travail sur le thread principal pendant l'animation (le script est nommé). « Forced layout » signifie qu'un script a lu la mise en page (offsetHeight, getBoundingClientRect) juste après avoir modifié les styles, généralement dans une boucle : lisez d'abord tout, puis écrivez |
slow-response | Un clic, Entrée, Espace ou Échap n'a rien montré pendant 100 ms ou plus | Aucun état pressé ou en attente pendant que le travail ou une requête s'exécute. Montrez-en un immédiatement. [cause: main thread busy …] signifie qu'un gestionnaire lent a empêché le rendu de la réponse |
layout-anim | Anime la largeur, la hauteur, le haut, la marge et autres | Exécute la mise en page à chaque frame. Correct pour les petits accordéons ; préférez les transformations pour les mouvements grands ou fréquents |
Les résultats de mouvement nomment l'animation qui déplaçait l'élément, ou un ancêtre, à ce frame : [animation: transition transform 300ms ease-out], [animation: animation slide-in 400ms ease on div.panel] ou [animation: Web Animation of opacity, transform 200ms linear]. Allez d'abord à cette règle ou cet appel. Aucune animation nommée signifie généralement que le mouvement est piloté par script (requestAnimationFrame, une bibliothèque de ressorts) ou n'est pas animé du tout.
Attentes
Passez expect (option ou --expect) pour obtenir des lignes pass/échec et un code de sortie 1 en cas d'échec :
{
"moves": { "[data-composer]": { "dy": 317, "tolerance": 2 } },
"still": "others",
"maxShift": 1,
"fadesIn": [".toast"],
"fadesOut": ["[role=dialog]"],
"noFindings": "medium"
}
moves: déplacement net du premier au dernier frame, en pixels. Si l'élément est remonté, il suit la copie qui est à l'écran.still: éléments qui ne doivent pas bouger de plus demaxShift. Utilisez"others"pour tout ce qui est présent en permanence et non nommé ailleurs. Un sélecteur qui ne correspond à rien échoue.fadesIn: l'élément doit être en dessous de 50 % d'opacité sur son premier frame visible et à 90 % ou plus à la fin.fadesOut: en dessous de 50 % sur son dernier frame visible.noFindings: aucun résultat à cette sévérité ou au-dessus, les changements non animés inclus.- L'option
--fail-on <severity>du moteur d'exécution se termine avec le code 1 en cas de défaut à cette sévérité ou au-dessus. Les changements non animés n'y comptent pas ; exigez un fondu avecfadesInoufadesOutà la place. - Tout sélecteur qui ne correspond à rien fait échouer son attente, donc une faute de frappe ne peut pas passer silencieusement.
Garder le rapport utile
- Limitez avec
rootà la région qui doit réagir. C'est plus rapide et plus silencieux. Les superpositions ajoutées en dehors sont toujours surveillées : tout ce qui est ajouté directement au<body>, les éléments en position fixe, et les fenêtres de dialogue, menus, popovers, infobulles et toasts (trouvés parrole,aria-modal,popoverou<dialog>). - Un
rootqui n'existe pas encore est attendu. Ce qu'il contient lorsqu'il apparaît est la référence, donc pour juger comment un panneau apparaît, utilisez une racine qui existe avant (ou aucune). - Un sous-arbre inséré en une fois (ou déplacé en place, comme le HTML diffusé en continu) est signalé comme un résultat unique nommant le sous-arbre et le nombre d'éléments qu'il contient.
- Seuls les éléments qui dessinent quelque chose (texte, arrière-plan, bordure, ombre, filtre d'arrière-plan, contenu
::before/::after, images, contrôles de formulaire) peuvent produire des résultats. Les wrappers transparents restent silencieux, ce sont donc leurs enfants peints qui rapportent. - Les animations CSS et Web Animations infinies (spinners, shimmer) sont ignorées automatiquement. Une boucle JavaScript qui ne s'arrête jamais et modifie les styles est signalée comme une dégradation continue ; le rapport le note.
- Les changements de mise en page (insertions, suppressions, redimensionnements) sont signalés une fois par frame où ils se produisent : le résultat
shiftliste tous les éléments déplacés ce frame-là plutôt qu'un résultat par élément. - Les résultats sont dédupliqués par élément et par type : si un élément a sauté et flashé dans la même interaction, les deux sont listés.
Aucune dépendance de build
Le dépôt publie les scripts pré-construits. Il n'y a ni bundler, ni compilateur, ni étape npm install dans le dossier de la compétence. Le code source se trouve dans scripts/ et peut être modifié directement.