fix

Présentation du fix skill

Ce que fait le fix skill

Le fix skill fournit un workflow de débogage ciblé pour les tests Playwright en échec ou instables. Il aide un agent IA à passer de « ce test est cassé » à une cause racine probable, en reproduisant l’échec, en collectant des traces exploitables, puis en classant le problème avec une taxonomie des tests flaky plutôt qu’en se fiant uniquement au message d’assertion.

Cas d’usage idéal pour le débogage de tests Playwright

Installez ce skill si vous maintenez des tests end-to-end et voyez régulièrement des messages comme « test failing », « flaky test », « passes locally but fails in CI » ou « intermittent failure ». Il est particulièrement utile pour les équipes qui utilisent Playwright en CI, où les échecs peuvent venir du timing, de l’isolation des tests, de différences d’environnement ou de la pression sur l’infrastructure.

Pourquoi il est plus utile qu’un prompt générique

Un prompt de débogage générique propose souvent de modifier le code trop vite. Le fix skill impose une meilleure séquence : reproduire d’abord, faire du burn-in si l’échec disparaît, capturer les traces, puis associer les symptômes à des catégories. Son fichier compagnon flaky-taxonomy.md fournit des branches de diagnostic et des modèles de correction concrets, notamment pour les await manquants, l’état partagé, les différences de viewport/police/fuseau horaire propres à la CI, les crashs de navigateur et l’instabilité liée aux workers.

Limites importantes avant l’installation

Ce n’est pas un correcteur de bugs universel. Il est centré sur les tests Playwright et suppose que l’agent peut inspecter votre fichier de test, exécuter des commandes Playwright et lire des sorties comme des traces, captures d’écran, logs ou messages d’échec CI. Il ne contient pas de scripts auxiliaires : sa valeur vient du workflow et de la taxonomie, pas de l’automatisation.

Comment utiliser le fix skill

Installation de fix et fichiers à inspecter en premier

Installez le skill dans un environnement compatible avec les skills avec :

npx skills add alirezarezvani/claude-skills --skill fix

Après l’installation, lisez d’abord SKILL.md pour comprendre le workflow d’exécution, puis ouvrez flaky-taxonomy.md pour l’arbre de décision et les corrections courantes. Le chemin du dépôt est engineering-team/playwright-pro/skills/fix, et les fichiers source utiles sont volontairement réduits : il n’y a pas de scripts, règles ou fichiers de métadonnées cachés à configurer.

Entrées dont le fix skill a besoin

Pour de meilleurs résultats, fournissez au moins l’un de ces éléments :

• Chemin du fichier de test, par exemple e2e/login.spec.ts
• Nom exact du test ou chaîne --grep
• Message d’échec, stack trace ou erreur d’assertion
• Indication sur l’environnement où l’échec se produit : localement, en CI ou les deux
• Précision indiquant s’il passe seul mais échoue dans la suite complète
• Chemin vers une trace, capture d’écran, vidéo ou artefact CI si disponible
• Configuration Playwright pertinente, en particulier workers, retries, projects, viewport, timezone et base URL

Prompt faible : « Fix my flaky checkout test. »

Prompt plus efficace : « Use the fix skill for Debugging e2e/checkout.spec.ts, test should submit paid order. It passes locally alone, fails in CI about 30% of runs, and the failure is Timeout 5000ms exceeded waiting for getByRole('button', { name: 'Pay' }). CI uses 4 workers and retries=2. Suggest the reproduction commands, likely category, and minimal code/config changes. »

Workflow pratique avec fix

Commencez par le fichier exact qui échoue :

npx playwright test <file> --reporter=list

S’il passe, considérez qu’il est potentiellement flaky et lancez un burn-in :

npx playwright test <file> --repeat-each=10 --reporter=list

Si le problème n’apparaît qu’en concurrence, exécutez avec du parallélisme :

npx playwright test --fully-parallel --workers=4 --repeat-each=5

Ensuite, capturez des traces :

npx playwright test <file> --trace=on --retries=0

Demandez à l’agent de classer l’échec avant toute modification. Les catégories attendues sont timing/async, isolation des tests, environnement ou infrastructure. Cela évite les mauvaises corrections courantes, comme ajouter un waitForTimeout arbitraire, augmenter les timeouts globaux ou masquer une vraie race condition derrière des retries.

Modèle de prompt pour de meilleurs résultats

Utilisez un prompt qui sépare les preuves de la demande :

« Use the fix skill. Diagnose before changing code. Test: <file> / <test name>. Reproduction result: <passes/fails command>. CI/local behavior: <details>. Trace or screenshot: <path or summary>. Current suspicion: <optional>. Please categorize using flaky-taxonomy.md, explain the evidence, propose the smallest safe fix, and list the command to verify it. »

Cette structure aide le skill à produire un plan de débogage vérifiable plutôt qu’un patch spéculatif.

FAQ du fix skill

Le fix skill sert-il uniquement aux tests flaky ?

Non. Le fix skill traite à la fois les tests Playwright qui échouent systématiquement et les échecs intermittents. Pour les échecs déterministes, il commence tout de même par la reproduction et la capture de traces. Pour les échecs intermittents, il ajoute du burn-in et des vérifications avec workers parallèles afin de révéler des schémas liés au timing, à l’isolation ou à l’infrastructure.

Quand faut-il éviter ce skill ?

Ne l’utilisez pas comme outil principal pour des tests unitaires, des tests d’intégration backend, des bugs de production sans couverture Playwright ou du débogage large d’architecture applicative. Il peut quand même donner des pistes générales, mais ses commandes, sa taxonomie et ses exemples sont écrits pour des tests end-to-end Playwright.

Quelle différence avec le Playwright trace viewer seul ?

Le trace viewer montre ce qui s’est passé ; le fix skill aide à décider ce que cela signifie. Par exemple, un élément manquant peut indiquer une race condition asynchrone, un état pollué par un test précédent, une différence de viewport en CI ou une dépendance réseau. La taxonomie transforme les artefacts en chemin de diagnostic et en type de correction suggéré.

Le fix skill est-il adapté aux débutants ?

Oui, si l’utilisateur peut exécuter des commandes Playwright et partager les erreurs. Les débutants profitent de la séquence de commandes explicite et du tableau de catégories. En revanche, le skill ne remplace pas les bases de configuration du projet : Playwright doit déjà être installé, la suite de tests doit pouvoir être exécutée et les artefacts doivent être accessibles.

Comment améliorer le fix skill

Fournir de meilleures preuves d’échec à fix

L’amélioration la plus importante consiste à fournir des entrées de meilleure qualité. Incluez les commandes exactes déjà essayées et leurs résultats. « Fails in CI » est moins utile que « fails in CI with 4 workers, passes locally with one worker, fails locally with --fully-parallel --workers=4 --repeat-each=5 ». Ce seul détail oriente vers un problème d’isolation ou de parallélisme plutôt que vers un simple souci générique de timing.

Éviter les pièges courants du débogage

Ne demandez pas de patch avant le diagnostic. Les mauvais résultats fréquents incluent l’ajout de pauses fixes, l’augmentation des timeouts globaux, l’activation de retries supplémentaires ou la réécriture de sélecteurs sans confirmation de la cause. Demandez au skill d’indiquer la catégorie, les preuves, la correction minimale et la commande de vérification avant de modifier le code.

Itérer après la première correction

Après avoir appliqué une modification proposée, relancez la plus petite commande de vérification réellement significative. Si la correction visait le timing, utilisez un burn-in. Si elle visait l’isolation, comparez le comportement du test seul avec celui de la suite. Si elle visait l’environnement CI, reproduisez avec des paramètres plus proches de la CI, comme Docker, les workers, le fuseau horaire, le viewport ou les services réseau mockés.

Adapter le guide fix à votre projet

Les équipes peuvent améliorer les résultats locaux en ajoutant des notes propres au projet à proximité du workflow du skill : paramètres CI courants, services connus pour être flaky, réinitialisations de données de test obligatoires, fixtures standard, stratégie de mocks et conventions de locators préférées. Le fix skill fonctionne mieux lorsque sa taxonomie est combinée aux véritables schémas d’échec de votre dépôt.