Étude de cas: Améliorer le débogage Angular avec les outils de développement

Victor Porof
Victor Porof
X GitHub
Bramus

Une expérience de débogage améliorée

Au cours des derniers mois, l'équipe des outils pour les développeurs Chrome a collaboré avec l'équipe Angular pour améliorer l'expérience de débogage dans les outils pour les développeurs Chrome. Les membres des deux équipes ont travaillé ensemble et ont pris des mesures pour permettre aux développeurs de déboguer et de profiler des applications Web du point de vue de l'auteur: en termes de langue source et de structure de projet, avec un accès à des informations familières et pertinentes pour eux.

Cet article vous présente les modifications apportées à Angular et aux outils de développement Chrome pour y parvenir. Même si certaines de ces modifications sont illustrées avec Angular, elles peuvent également être appliquées à d'autres frameworks. L'équipe Chrome DevTools encourage les autres frameworks à adopter les nouvelles API de console et les points d'extension de la carte source afin qu'ils puissent également offrir une meilleure expérience de débogage à leurs utilisateurs.

Code d'ignorement de la fiche

Lorsque vous déboguez des applications à l'aide des outils pour les développeurs Chrome, vous ne souhaitez généralement voir que votre code, et non celui du framework sous-jacent ni une dépendance cachée dans le dossier node_modules.

Pour ce faire, l'équipe DevTools a introduit une extension des cartes sources, appelée x_google_ignoreList. Cette extension permet d'identifier les sources tierces telles que le code de framework ou le code généré par le bundler. Lorsqu'un framework utilise cette extension, les auteurs évitent désormais automatiquement le code qu'ils ne souhaitent pas voir ou suivre sans avoir à le configurer manuellement au préalable.

En pratique, Chrome DevTools peut automatiquement masquer le code identifié comme tel dans les traces de pile, l'arborescence des sources, la boîte de dialogue "Ouvrir rapidement", et améliorer le comportement de pas à pas et de reprise dans le débogueur.

GIF animé montrant DevTools avant et après. Notez que dans l'image d'après, les outils DevTools affichent le code créé dans l'arborescence, ne suggèrent plus aucun fichier de framework dans le menu "Ouvrir rapidement" et affichent une trace de pile beaucoup plus claire à droite.

Extension de carte source x_google_ignoreList

Dans les mappages de sources, le nouveau champ x_google_ignoreList fait référence au tableau sources et liste les indices de toutes les sources tierces connues de ce mappage de sources. Lors de l'analyse du mappage source, Chrome DevTools l'utilise pour déterminer quelles sections du code doivent être ajoutées à la liste d'éléments à ignorer.

Vous trouverez ci-dessous une carte source pour un fichier out.js généré. Deux sources d'origine ont contribué à générer le fichier de sortie: foo.js et lib.js. Le premier est un code écrit par un développeur de site Web, et le second est un framework qu'il a utilisé.

{
  "version" : 3,
  "file": "out.js",
  "sourceRoot": "",
  "sources": ["foo.js", "lib.js"],
  "sourcesContent": ["...", "..."],
  "names": ["src", "maps", "are", "fun"],
  "mappings": "A,AAAB;;ABCDE;"
}

sourcesContent est inclus pour ces deux sources d'origine, et les outils pour les développeurs Chrome affichent ces fichiers par défaut dans le débogueur:

  • En tant que fichiers dans l'arborescence "Sources".
  • dans la boîte de dialogue "Ouvrir rapidement".
  • En tant qu'emplacements de frame d'appel mappés dans les traces de pile d'erreur lorsque vous êtes arrêté sur un point d'arrêt et lorsque vous effectuez une étape.

Une information supplémentaire peut désormais être incluse dans les maps de sources pour identifier laquelle de ces sources est du code propriétaire ou tiers:

{
  ...
  "sources": ["foo.js", "lib.js"],
  "x_google_ignoreList": [1],
  ...
}

Le nouveau champ x_google_ignoreList contient un seul indice faisant référence au tableau sources: 1. Cela spécifie que les régions mappées sur lib.js sont en fait du code tiers qui doit être automatiquement ajouté à la liste d'éléments à ignorer.

Dans un exemple plus complexe, illustré ci-dessous, les indices 2, 4 et 5 indiquent que les régions mappées sur lib1.ts, lib2.coffee et hmr.js sont toutes du code tiers qui doit être automatiquement ajouté à la liste d'ignorer.

{
  ...
  "sources": ["foo.html", "bar.css", "lib1.ts", "baz.js", "lib2.coffee", "hmr.js"],
  "x_google_ignoreList": [2, 4, 5],
  ...
}

Si vous êtes développeur de framework ou de bundler, assurez-vous que les mappages sources générés lors du processus de compilation incluent ce champ afin de pouvoir exploiter ces nouvelles fonctionnalités dans les outils de développement Chrome.

x_google_ignoreList dans Angular

À partir de la version Angular v14.1.0, le contenu des dossiers node_modules et webpack a été marqué comme "à ignorer".

Pour ce faire, nous avons modifié angular-cli en créant un plug-in qui s'associe au module Compiler de webpack.

Le plug-in webpack créé par nos ingénieurs s'intègre à l'étape PROCESS_ASSETS_STAGE_DEV_TOOLING et renseigne le champ x_google_ignoreList dans les mappages sources pour les éléments finaux générés par webpack et chargés par le navigateur.

const map = JSON.parse(mapContent) as SourceMap;
const ignoreList = [];

for (const [index, path] of map.sources.entries()) {
  if (path.includes('/node_modules/') || path.startsWith('webpack/')) {
    ignoreList.push(index);
  }
}

map[`x_google_ignoreList`] = ignoreList;
compilation.updateAsset(name, new RawSource(JSON.stringify(map)));

Traces de pile associées

Les traces de pile répondent à la question "Comment suis-je arrivé ici ?", mais souvent du point de vue de la machine, et pas nécessairement de celui du développeur ni de son modèle mental de l'environnement d'exécution de l'application. Cela est particulièrement vrai lorsque certaines opérations sont planifiées pour se produire de manière asynchrone plus tard: il peut toujours être intéressant de connaître la "cause racine" ou le côté planification de ces opérations, mais c'est exactement ce qui ne figurera pas dans une trace de pile asynchrone.

V8 dispose en interne d'un mécanisme permettant de suivre ces tâches asynchrones lorsque des primitives de planification de navigateur standard sont utilisées, telles que setTimeout. Dans ces cas, cela est effectué par défaut, de sorte que les développeurs puissent déjà les inspecter. Toutefois, dans les projets plus complexes, ce n'est pas aussi simple, en particulier lorsque vous utilisez un framework avec des mécanismes de planification plus avancés, par exemple un framework qui effectue le suivi des zones, la mise en file d'attente de tâches personnalisées ou qui divise les mises à jour en plusieurs unités de travail exécutées au fil du temps.

Pour résoudre ce problème, DevTools expose un mécanisme appelé "API de taggage de pile asynchrone" sur l'objet console, qui permet aux développeurs de framework d'indiquer à la fois les emplacements où les opérations sont planifiées et les emplacements où elles sont exécutées.

API Async Stack Tagging

Sans le taggage de pile asynchrone, les traces de pile du code exécuté de manière asynchrone de manière complexe par les frameworks s'affichent sans aucune connexion au code où il a été planifié.