Framework de Reproduction de Bug
Étant donné un contexte de ticket Linear ($ARGUMENTS), reproduire systématiquement le bug avec un test de régression défaillant.
Étape 1 : Analyser les Signaux
Extraire les éléments suivants du contexte de ticket fourni :
- Message d'erreur / stack trace (si fourni)
- Étapes de reproduction (si fournies)
- Workflow JSON (si joint)
- Zone affectée (nœud, moteur d'exécution, éditeur, API, config, etc.)
- Version où ça a cassé / dernière version fonctionnelle
Étape 2 : Router vers la Stratégie de Test
En fonction de la zone affectée, choisir la couche de test et le pattern :
| Zone | Couche de Test | Pattern | Emplacement Clé |
|---|---|---|---|
| Opération nœud | Jest unit | NodeTestHarness + nock | packages/nodes-base/nodes/*/test/ |
| Credential nœud | Jest unit | jest-mock-extended | packages/nodes-base/nodes/*/test/ |
| Webhook trigger | Jest unit | mock IHookFunctions + jest.mock GenericFunctions | packages/nodes-base/nodes/*/test/ |
| Données binaires | Jest unit | NodeTestHarness assertBinaryData | packages/core/nodes-testing/ |
| Moteur d'exécution | Jest integration | WorkflowRunner + DI container | packages/cli/src/__tests__/ |
| CLI / API | Jest integration | setupTestServer + supertest | packages/cli/test/integration/ |
| Config | Jest unit | GlobalConfig + Container | packages/@n8n/config/src/__tests__/ |
| Éditeur UI | Vitest | Vue Test Utils + Pinia | packages/frontend/editor-ui/src/**/__tests__/ |
| E2E / Canvas | Playwright | Test containers + composables | packages/testing/playwright/ |
Étape 3 : Localiser les Fichiers Source
Trouver le code source de la zone affectée :
- Chercher le nœud/service/composant mentionné dans le ticket
- Trouver le fichier GenericFunctions (emplacement de bug courant pour les nœuds)
- Vérifier les fichiers de test existants dans la même zone
- Consulter l'historique git récent sur les fichiers affectés (
git log --oneline -10 -- <path>)
Étape 4 : Tracer le Chemin du Code
Lire le code source et tracer le chemin d'exécution qui déclenche le bug :
- Suivre la chaîne d'appels du point d'entrée jusqu'à la défaillance
- Identifier la/les ligne(s) spécifique(s) où le bug se manifeste
- Noter tout traitement d'erreur (ou son absence) autour du bug
Étape 5 : Formuler une Hypothèse
Énoncer une hypothèse claire et testable :
- « Quand [entrée/condition], le code [fait la mauvaise chose] parce que [cause racine] »
- Identifier la/les ligne(s) exacte(s) qui doivent changer
- Prédire ce que la sortie du test montrera
Étape 6 : Trouver les Patterns de Test
Chercher les tests existants dans la même zone :
- Vérifier les répertoires
test/près du code affecté - Identifier quels patterns mock/setup ils utilisent
- Utiliser les mêmes patterns pour la cohérence
- S'il n'existe pas de tests, trouver le test de nœud/service similaire le plus proche comme template
Étape 7 : Écrire un Test Défaillant
Écrire un test de régression qui :
- Utilise les patterns trouvés à l'Étape 6
- Cible l'hypothèse spécifique de l'Étape 5
- Inclut un commentaire référençant l'ID du ticket
- Affirme le comportement CORRECT (le test échouera sur le code actuel)
- Inclut aussi un test « happy path » pour prouver que la configuration fonctionne
Étape 8 : Exécuter et Évaluer
Exécuter le test depuis le répertoire du package (ex. : cd packages/nodes-base && pnpm test <file>).
Classer le résultat :
| Confiance | Critères | Sortie |
|---|---|---|
| CONFIRMED | Le test échoue régulièrement, l'échec correspond à l'hypothèse | Rapport de Reproduction |
| LIKELY | Le test échoue mais le mode d'échec diffère légèrement | Rapport + caveat |
| UNCONFIRMED | Impossible de déclencher l'échec | Rapport : ce qui a été essayé |
| SKIPPED | Déclenchement d'un arrêt difficile atteint | Rapport : pourquoi ignoré |
| ALREADY_FIXED | Le bug ne se reproduit plus sur le code actuel | Rapport : quand corrigé |
Étape 9 : Itérer ou Arrêter
Si UNCONFIRMED après la première tentative :
- Revoir l'hypothèse — relire le chemin du code
- Essayer une approche ou une couche de test différente
- Maximum 3 tentatives avant de déclarer UNCONFIRMED
Déclencheurs d'arrêt difficile (arrêter immédiatement) :
- Nécessite des credentials API tierce réels
- Race condition / dépendant du timing
- Nécessite une infrastructure cloud/entreprise spécifique
- Nécessite une interaction UI manuelle qui ne peut pas être scriptée
Sortie : Rapport de Reproduction
Présenter les résultats dans ce format :
Ticket : [ID] — [titre] Confiance : [CONFIRMED | LIKELY | UNCONFIRMED | SKIPPED | ALREADY_FIXED]
Cause Racine
[1-2 phrases expliquant le mécanisme du bug]
Emplacement
| Fichier | Lignes | Problème |
|---|---|---|
path/to/file.ts |
XX-YY | Description du problème |
Test Défaillant
path/to/test/file.test.ts — X/Y tests échouent :
nom du test— [description de l'échec]
Indice pour la Correction
[Pseudocode ou description de l'approche de correction]
Important
- NE PAS corriger le bug — seulement le reproduire avec un test défaillant
- Laisser les fichiers de test en place comme preuve (ne commiter que si demandé)
- Exécuter les tests depuis le répertoire du package (ex. :
pushd packages/nodes-base && pnpm test <file> && popd) - Toujours rediriger la sortie de build :
pnpm build > build.log 2>&1 - NE PAS consulter les PRs de correction existantes — l'objectif est de reproduire à partir des signaux seuls