jaimegago/agent-skills

Débogage d'exécution Frontend : inspecter l'état en direct avant de relire le code source

Les données sont correctes sur le réseau mais l'interface utilisateur est erronée. C'est un bug d'exécution/timing, et l'instinct qui vous fera perdre du temps est de relire les fichiers source. Résistez-y. Réorganisez votre réflexe.

Quand l'utiliser

Invoquez-le en cours de débogage, lorsque le symptôme apparaît — pas au début de la tâche. Utilisez-le lorsque TOUTES ces conditions sont réunies :

• Un composant React ne rend rien, affiche des données obsolètes ou du contenu vide.
• Les données dont il a besoin sont connues pour être correctes à la source (l'API/backend renvoie la bonne réponse).
• L'écart se situe quelque part entre « réponse correcte sur le réseau » et « rendu correct à l'écran ».

Formulations typiques : « l'API renvoie les bonnes données mais le composant est vide », « react-query est bloqué », « la requête est 200 mais l'interface ne se met jamais à jour », « ça fonctionne après un rafraîchissement mais pas au premier chargement ».

À quoi cela ne sert PAS

• Erreurs de construction / compilation — c'est un bug d'outillage, pas un bug d'exécution.
• Problèmes de style / mise en page uniquement — les données s'affichent, mais l'apparence est incorrecte.
• L'API renvoie effectivement des données erronées ou aucune donnée — c'est un bug normal de contrat/backend. Vérifiez D'ABORD la réponse réseau ; si la réponse est réellement erronée ou vide, arrêtez-vous et corrigez le contrat/backend. Cette compétence est uniquement pour quand le réseau est correct mais que l'interface ne l'est pas.

La réorganisation (la leçon essentielle)

1. Inspectez l'état d'exécution en direct AVANT de relire le code source. Le réflexe est de relire le composant, le schéma, la mise en page et le câblage du fournisseur à la recherche du bug. Quand les données sont correctes sur le réseau mais que l'interface utilisateur est erronée, ce réflexe est un piège : le bug ne se trouve souvent PAS dans un seul fichier source mais dans une interaction d'exécution/timing entre des morceaux qui sont chacun individuellement corrects. La revue de code source est structurellement aveugle à cette classe de bugs. Examinez d'abord l'état en direct.

2. Un 200 dans le panneau réseau peut activement induire en erreur. Une requête affichant 200 signifie que la réponse est arrivée. Cela ne signifie PAS que les données ont atteint le composant ou ont été validées dans le cache. La réponse peut arriver puis être rejetée, supprimée ou jamais validée. Ne concluez pas « la récupération fonctionne » à partir d'un seul 200 — confirmez que les données ont réellement atteint l'état du composant consommateur.

3. Pour react-query, inspectez l'observateur de requête en direct du composant affecté, pas seulement le réseau. Lisez le status, fetchStatus, dataUpdateCount et error de l'observateur.

   • Une requête bloquée avec status: "pending" / fetchStatus: "fetching" et dataUpdateCount: 0 signifie que le résultat de la promesse queryFn n'a jamais été validé dans l'observateur. Cela pointe vers une requête supprimée ou invalidée en cours d'exécution — PAS vers un échec de récupération.
   • Confirmez que le queryFn lui-même est sain en forçant un rafraîchissement de l'observateur. Si un rafraîchissement manuel se résout correctement et immédiatement, la récupération/le client/le schéma sont tous corrects, et le vrai bug est que la requête initiale a été abandonnée (supprimée par une purge du cache, invalidée par un effet, ou démontée par un remontage). Cette seule observation permet de distinguer « le chemin de données est cassé » de « le chemin de données est correct mais la requête a été tuée » — des bugs complètement différents.

4. Une fois localisé sur « requête abandonnée en cours d'exécution », recherchez en amont dans le cycle de vie/la gestion du cache. La cause est quelque chose qui s'est exécuté au même moment que le démarrage de la requête : un removeQueries / invalidateQueries / réinitialisation du cache, ou une course montage/démontage/remontage. Examinez les effets de transition d'authentification/session, les purges liées au changement de principal/locataire et les remontages de fournisseurs — PAS le code de récupération.

Arbre de décision

UI erronée, données correctes à la source ?
  → confirmez que la réponse réseau est réellement correcte (pas le travail de cette compétence si ce n'est pas le cas)
  → lisez l'observateur de requête en direct du composant affecté
       status pending + fetchStatus fetching + dataUpdateCount 0 ?
          → forcez un rafraîchissement sur cet observateur
               le rafraîchissement se résout instantanément et correctement ?
                  → queryFn est OK. Bug = requête initiale abandonnée.
                    Cherchez en amont : removeQueries/invalidateQueries/reset,
                    course remontage/démontage, effet de purge auth/session/locataire.
               le rafraîchissement échoue aussi ?
                  → le chemin de données est vraiment cassé. Inspectez queryFn/client/schéma.
       a des données mais l'UI est toujours vide ?
          → bug de rendu/sélecteur/conditionnel dans le composant, relisez maintenant le code source.

Outils d'inspection en direct (pistes, pas des API stables)

Ces extraits atteignent l'observateur react-query d'un composant à partir d'une page en cours d'exécution en parcourant l'arbre Fiber React à partir d'un élément DOM rendu, lisent l'état actuel de la requête de l'observateur et forcent un rafraîchissement pour prouver que le queryFn fonctionne.

Ces extraits sont sensibles aux versions. Ils ont été dérivés de @tanstack/react-query v5.90 et des internes du Fiber React 18, reposent sur des internes non documentés et VONT dériver. Traitez-les comme des points de départ à adapter — revérifiez les noms de champ et la forme du Fiber par rapport aux versions installées du projet avant de vous fier à un résultat. Ce sont des pistes, pas des API garanties stables.

Parcourez l'arbre Fiber à partir d'un nœud DOM pour trouver les hooks/observateurs :

// Choisissez un élément DOM rendu par le composant affecté (par exemple via $0 dans les devtools).
const el = $0; // ou document.querySelector('[data-testid="..."]')
const key = Object.keys(el).find(k => k.startsWith('__reactFiber$'));
let fiber = el[key];

// Parcourez l'arbre Fiber vers le haut/bas ; memoizedState est une liste chaînée de hooks.
// react-query stocke son observateur sur le memoizedState d'un hook.
function* fibers(root) {
  const stack = [root];
  while (stack.length) {
    const f = stack.pop();
    if (!f) continue;
    yield f;
    if (f.child) stack.push(f.child);
    if (f.sibling) stack.push(f.sibling);
  }
}

// Analysez l'état des hooks pour trouver quelque chose qui ressemble à un QueryObserver.
function findObservers(fiber) {
  const found = [];
  for (const f of fibers(fiber)) {
    let hook = f.memoizedState;
    while (hook) {
      const s = hook.memoizedState;
      if (s && typeof s === 'object') {
        // Les instances de QueryObserver exposent getCurrentResult()/getCurrentQuery().
        if (typeof s.getCurrentResult === 'function') found.push(s);
        // Certaines versions l'imbriquent ; vérifiez aussi les wrappers courants.
        if (s.observer && typeof s.observer.getCurrentResult === 'function') found.push(s.observer);
      }
      hook = hook.next;
    }
  }
  return found;
}

const observers = findObservers(fiber);

Lisez l'état de la requête en direct d'un observateur :

const obs = observers[0];
const r = obs.getCurrentResult();
console.log({
  status: r.status,            // 'pending' | 'error' | 'success'
  fetchStatus: r.fetchStatus,  // 'fetching' | 'paused' | 'idle'
  dataUpdateCount: obs.getCurrentQuery().state.dataUpdateCount,
  error: r.error,
});
// pending + fetching + dataUpdateCount 0  ==>  abandonné en vol, pas un échec de récupération.

Forcez un rafraîchissement pour prouver que le queryFn est sain :

obs.refetch().then(r => console.log('refetch:', r.status, r.data)).catch(e => console.log('refetch failed:', e));
// Se résout instantanément et correctement  ==>  queryFn/client/schéma sont corrects ;
//                                                 la requête originale a été tuée en amont.

Si le projet expose le QueryClient (par exemple sur window pour le débogage, ou accessible depuis un Fiber fournisseur), préférez queryClient.getQueryCache().findAll() et inspectez directement l'state et les observers de chaque requête — c'est plus robuste que le parcours du Fiber, quand c'est disponible.

Complétion

Lorsque vous avez localisé le bug :

1. Indiquez de quel côté de la fourchette il se trouve : « chemin de données cassé » ou « requête abandonnée ».
2. Si abandonné, nommez l'action de cycle de vie/cache en amont qui l'a tué.
3. Alors seulement, relisez le fichier source spécifique responsable — maintenant vous savez lequel.