Cet article explique comment vous pouvez utiliser les outils de développement de Firefox pour déboguer les WebExtensions.

Une extension peut se composer de diverses pièces différentes — scripts de fond, fenêtes contextuelles, pages d'options, scripts de contenu — et vous devrez utiliser un flux de travail légèrement différent pour déboguer chaque pièce. Donc, chaque pièce reçoit une section de haut niveau dans cet article, et l'intention est que ces sections peuvent être lues séparemment. Nous commencerons par présenter le débogueur d'extensions, que vous utiliserez pour déboguer la plupart des éléments de votre extension.

Le débogger d'extension

La plupart de cet article, nous utiliserons le débogueur d'extension. Pour ouvrir le débogueur extension :

  • Ouvrir Firefox
  • Entrez "about:debugging" dans la barre de l'URL
  • Cliquez sur "Charger une extension complémentaire"
  • Cliquez sur le bouton "Déboguer" à côté de votre extension
  • Cliquez sur "OK" dans la boîte de dialogue d'avertissement

Vous verrez alors une nouvelle fenêtre. La fenêtre principale de Firefox sera transférée au premier plan, donc vous devrez cliquer sur la nouvelle fenêtre pour la mettre en avant.

Cette nouvelle fenêtre est parfois appelée une "boîte à outils" et contient les outils de débogage que nous utiliserons. Il a une interface d'onglets: la rangée d'onglets le long en haut vous permet de basculer entre les différents outils :

Dans cet article, nous utiliserons trois outils de débogage:

  • La Console: cela affiche les messages enregistrés par l'extension ainsi que les messages d'erreur enregistrés par le navigateur car il exécute l'extension. Il fournit également une ligne de commande vous permettant d'exécuter JavaScript dans le contexte de l'extension.
  • Le Debogueur: cela vous permet de définir des points d'arrêt et des points de contrôle dans le JavaScript de votre extension, et d'examiner et de modifier son état interne.
  • L'Inspecteur: cela vous permet d'examiner et de modifier le HTML et le CSS utilisés pour créer les pages de votre extension.

Déboguer les scripts d'arrière-plan

Les exemples de cette section utilisent l'extension d'exemple "notify-link-clicks-l10n". Si vous souhaitez jouer, vous pouvez trouver cet exemple dans le dépôt webextensions-examples.

Les scripts d'arrière-plan restent chargés pendant toute la durée de l'extension.  Ils sont chargés dans une  "page d'arrière-plan" invisible : par defaut, il s'agit d'un document HTML vide, mais vous pouvez spécifier votre propre contenu HTML à l'aide de la clé "background" dans "manifest.json".

Vous pouvez déboguer les scripts de fond à l'aide du Débogueur d'extension.

Dans la Console du débogueur d'extensions, vous verrez la sortie enregistrée, y compris les appels à console.log() à partir de vos propres scripts de fond et des erreurs que le navigateur déclenche au fur et à mesure qu'il les exécute. Notez que pour le moment, la console affiche toutes les erreurs soulevées par le navigateur, pas seulement les erreurs liées à votre code d'extension.

Par exemple, l'extension d'exemple notify-link-clicks-i18n enregistre un message à partir de son script d'arrière-plan lorsqu'il reçoit un message de l'un de ses scripts de contenu :

En utilisant la ligne de commande de la console, vous pouvez accéder et modifier les objets créés par vos scripts d'arrière-plan.

Par exemple, nous appelons la fonction notify() définie dans le script d'arrière-plan de l'extension:

Si vous passez au débogueur, vous verrez tous les scripts d'arrière-plan de votre extension. Vous pouvez définir des points d'arrêt, passer le code, et faire tout ce que vous attendez d'être capable de faire dans un débogueur.

Si vous appuyez sur la touche échape pendant que vous êtes dans le Débogueur, la boîte à outils sera divisée, la moitié inférieure maintenant occupée par la Console. Pendant que vous êtes dans un point d'arrêt, vous pouvez maintenant modifier l'état du programme à l'aide de la console. Voir Split console pour en savoir plus.

Déboguer les pages d'options

Les pages d'options sont des pages HTML que le développeur d'extension peut fournir, qui contiennent des options pour l'add-on. Ils sont généralement affichés dans un iframe dans le Gestionnaire des extensions (pour voir le Gestionnaire des Add-ons, visitez la page "about:addons").

Pour déboguer les pages d'options:

Toutes les sources JavaScript inclues sont listées dans le débogueur:

Cette vidéo utilise l'exemple WebExtension favourite-colour.

Vous verrez également les messages enregistrés par votre code dans la Console du débogueur d'extensions.

Vous pouvez également utiliser le débogueur d'extensions pour déboguer les pages HTML et CSS. Tout d'abord, vous devez pointer les outils à l'iframe qui héberge la page d'options. Pour ce faire: ouvrez la page d'options, cliquez sur l'icône mise en surbrillance dans la capture d'écran ci-dessous et sélectionnez la page d'options dans la liste déroulante:

Passez maintenant à l'onglet Inspecteur, et vous pourrez examiner et modifier le HTML et le CSS de la page :

Déboguer les popups

Les popups sont des boîtes de dialogue qui sont attachées aux actions du navigateur ou aux actions de la page. Ils sont spécifiés à l'aide d'un document HTML qui peut inclure des sources CSS et JavaScript pour le style et le comportement. haque fois que le popup est visible, vous pouvez utiliser le débogueur des extensions pour déboguer son code.

Un problème avec les popups est que si une popup est ouverte et que vous cliquez en dehors de la popup, la popup est fermée et son code est déchargé. Cela les rend évidemment impossibles à déboguer. Pour supprimer ce comportement, sélectionnez Disable Popup Auto-Hide dans le menu Elipsis comme indiqué ci-dessous :

Maintenant, lorsque vous ouvrez une fenêtre contextuelle, elle reste ouverte jusqu'à ce que vous appuyiez sur Échap.

Note: Cette modification s'applique aux fenêtres contextuelles intégrées au navigateur, comme le menu Elipsis (...), ainsi qu'aux fenêtres contextuelles d'extension.

Le paramètre ne persiste pas d'une session à l'autre. Lorsque vous fermez la fenêtre, le réglage revient au masquage automatique des fenêtres contextuelles.

En interne, ce bouton bascule simplement la préférence  ui.popup.disable_autohide que vous pouvez basculer manuellement en utilisant  about:config.

Lorsque le popup est ouvert, ses sources JavaScript seront listées dans le Debugger. Vous pouvez définir des points d'arrêt et modifier l'état interne du programme :

Cette vidéo utilise l'extension d'exemple beastify.

Vous pouvez également utiliser le débogueur d'extensions pour déboguer les HTML et CSS du popup. Tout d'abord, vous devez pointer les outils dans le document contextuel. Pour ce faire : Ouvrez le popup, puis cliquez sur l'icône mis en surbrillance dans la capture d'écran ci-dessous et sélectionnez la page contextuelle dans la liste déroulante :

Passez maintenant à l'inspecteur, et vous pourrez examiner et modifier le HTML et CSS du popup :

Déboguer les scripts de contenu

Vous pouvez utiliser le débogueur d'extension pour déboguer les pages d'arrière-plan, les pages d'options et les popups. Toutefois, vous ne pouvez pas l'utiliser pour déboguer les scripts de contenu. C'est parce que, dans le  Firefox multiprocessus, Les scripts de contenu s'exécutent dans un processus différent des autres parties de votre extension. La console de navigation a des limitations similaires.

Pour déboguer les scripts de contenu attachés à une page Web, utilisez les outils de développement Web normaux pour cette page:

  • Soit sélectionnez "Toggle Tools" dans le sous-menu Developpeur Web dans le menu Firefox (ou le menu Outils si vous affichez la barre de menu ou sur Mac OS X)
  • Ou appuyez sur le clavier CtrlShiftI (CommandOptionI sur OS X).

Par défaut, les outils sont affichés en bas de l'onglet du navigateur, afin de refléter le fait qu'ils sont attachés à cet onglet. Vous verrez une sortie des instructions console.log() dans vos scripts de contenu. Vous verrez également vos scripts de contenu répertoriés dans le Débogueur, où vous pourrez définir des points d'arrêt, parcourir le code, etc.

Cette vidéo utilise l'exemple WebExtension notify-link-clicks-i18n

Si l'onglet Outils de développement n'était pas déjà ouvert lorsque le script de contenu a été injecté, le script de contenu n'est pas listé dans le panneau de débogage. Si vous rencontrez cela, le rechargement de la page avec l'onglet Outils du développeur ouvert devrait résoudre le problème.

Débogage des barres latérales

Les barres latérales sont des pages HTML ouvertes en tant que barre latérale dans l'interface utilisateur du navigateur que le développeur d'extension peut fournir.

Pour déboguer les barres latérales :

Toutes les sources JavaScript qu'il inclut sont alors listées dans le Debugger.

Vous verrez également tous les messages enregistrés par votre code dans la console de débogage du débogueur de votre module complémentaire.

Vous pouvez également utiliser le débogueur de votre module complémentaire pour déboguer le HTML et le CSS de la page. Tout d'abord, vous devez pointer les outils sur l'iframe qui héberge la page d'options. Pour ce faire : ouvrez la barre latérale, cliquez sur l'icône en surbrillance dans la capture d'écran ci-dessous et sélectionnez la barre latérale dans la liste déroulante :

Débogage des pages et panneaux des outils de développements

Les outils de développement sont étendus en chargeant une page HTML cachée lorsque devtools sont ouverts et les panneaux des outils de développpement sont des pages HTML affichées en tent qu'outil de développement dans l'interface utilisateur du navigateur que le développeur d'extension peut fournir.

Déboguer la page des outils de développement :

Pour déboguer les panneaux des outils de développement :

  • Suivez les étapes de la page des outils de développement ci-dessus
  • Sélectionnez votre panneau d'outils de développement

Toutes les sources JavaScript qu'il inclut sont alors listées dans le Debugger

Vous verrez également tous les messages enregistrés par votre code dans la console de débogage de l'Add-on Debugger.

Vous pouvez également utiliser le débogueur de l'Add-on pour déboguer le HTML et le CSS de la page. Tout d'abord, vous devez pointer les outils sur l'iframe qui héberge la page d'options. Pour ce faire : ouvrez la barre latérale, cliquez sur l'icône en surbrillance dans la capture d'écran ci-dessous et sélectionnez la barre latérale dans la liste déroulante :

Redémarrage du navigateur après le débogage

Si votre extension est active d'une manière qui pourrait être affectée par le redémarrage du navigateur, comme une session en cours de restauration, vous voudrez peut-être faire des tests supplémentaires pour vous assurer que votre code fonctionne comme prévu dans ces conditions.

Voir Tester les fonctions persistantes et de redémarrage pour plus de détails.

Étiquettes et contributeurs liés au document

Contributeurs à cette page : hellosct1, kabanon
Dernière mise à jour par : hellosct1,