Les extensions permettent d'accéder aux mêmes outils pour les développeurs Chrome que les pages Web. Pour devenir un expert en débogage des extensions, vous devez savoir comment localiser les journaux et les erreurs des différents composants d'extension. Ce tutoriel fournit des techniques de base pour déboguer votre extension.
Avant de commencer
Ce guide suppose que vous disposez d'une expérience de base en développement Web. Nous vous recommandons de lire l'article Principes de base du développement pour une introduction au workflow de développement des extensions. L'article Concevoir l'interface utilisateur présente les éléments de l'interface utilisateur disponibles dans les extensions.
Déchiffrer l'extension
Ce tutoriel explique comment résoudre un composant d'extension à la fois, puis comment le résoudre. N'oubliez pas d'annuler les bugs introduits dans une section avant de passer à la section suivante. Commencez par télécharger l'exemple de couleur défectueuse sur GitHub.
Déboguer le fichier manifeste
Tout d'abord, interrompons le fichier manifeste en remplaçant la clé "version"
par "versions"
:
manifest.json:
{
"name": "Broken Background Color",
"version": "1.0",
"versions": "1.0",
"description": "Fix an Extension!",
...
}
Essayons maintenant de charger l'extension localement. Une boîte de dialogue d'erreur indiquant le problème s'affiche:
Failed to load extension
Required value version is missing or invalid. It must be between 1-4 dot-separated integers each between 0 and 65536.
Could not load manifest.
![Extension avec une clé de fichier manifeste non valide déclenchant une boîte de dialogue d'erreur lors de la tentative de chargement.](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/an-extension-an-invalid-9ab91f867f94c.png?authuser=6&hl=fr)
Lorsqu'une clé de fichier manifeste n'est pas valide, l'extension ne se charge pas, mais Chrome vous indique comment résoudre le problème.
Annulez cette modification et saisissez une autorisation non valide pour voir ce qui se passe.
Remplacez l'autorisation "activeTab"
par "activetab"
en minuscules:
manifest.json:
{
...
"permissions": ["activeTab", "scripting", "storage"],
"permissions": ["activetab", "scripting", "storage"],
...
}
Enregistrez l'extension, puis réessayez de la charger. Cette fois-ci, il devrait se charger correctement. La page de gestion des extensions comporte trois boutons: Details (Détails), Remove (Supprimer) et Errors (Erreurs). Le libellé du bouton Erreurs devient rouge en cas d'erreur. Cliquez sur le bouton Erreurs pour afficher l'erreur suivante:
Permission 'activetab' is unknown or URL pattern is malformed.
![Clic sur le bouton "Erreur" et affichage d'une erreur](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/error-button-is-clicked-a7713a11553a.gif?authuser=6&hl=fr)
Avant de continuer, rétablissez l'autorisation, cliquez sur Tout effacer en haut à droite pour effacer les journaux et actualisez l'extension.
![Bouton "Tout effacer"](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/clear-button-2f67dd9230519.png?authuser=6&hl=fr)
Déboguer le service worker
Localiser des journaux
Le service worker définit la couleur par défaut sur "storage" et l'enregistre dans la console. Pour afficher ce journal, ouvrez le panneau "Outils pour les développeurs Chrome" en sélectionnant le lien bleu à côté de l'option Inspecter les vues.
![Ouverture des outils de développement pour le service worker d'extension.](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/opening-devtools-the-ex-685e204e20773.png?authuser=6&hl=fr)
Localiser les erreurs
Interrompons le service worker en remplaçant onInstalled
par oninstalled
minuscule:
service-worker.js :
// There's a typo in the line below;
// ❌ oninstalled should be ✅ onInstalled.
chrome.runtime.onInstalled.addListener(() => {
chrome.runtime.oninstalled.addListener(() => {
chrome.storage.sync.set({ color: '#3aa757' }, () => {
console.log('The background color is green.');
});
});
Actualisez la page et cliquez sur Erreurs pour afficher le journal d'erreurs. La première erreur vous indique que le service worker n'a pas pu s'enregistrer. Cela signifie qu'une erreur s'est produite lors du lancement:
Service worker registration failed. Status code: 15.
![Échec de l'enregistrement du service worker. Code d'état: message d'erreur 15](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/service-worker-registrati-9791df79120e6.png?authuser=6&hl=fr)
L'erreur réelle s'affiche après:
Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')
![Erreur de type non détectée: impossible de lire les propriétés d'un message d'erreur non défini](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/uncaught-typeerror-canno-45ae014961338.png?authuser=6&hl=fr)
Annulez le bug que nous avions introduit, cliquez sur Tout effacer en haut à droite, puis actualisez l'extension.
Vérifier l'état du service worker
Pour identifier le moment où le service worker se réveille pour effectuer des tâches, procédez comme suit:
- Copiez l'ID de l'extension situé au-dessus de "Inspecter les vues".
ID d'extension sur la page "Gestion des extensions". - Ouvrez le fichier manifeste dans le navigateur. Par exemple :
text chrome-extension://YOUR_EXTENSION_ID/manifest.json
- Inspectez le fichier.
- Accédez au panneau Application.
- Accédez au volet Service workers (Service workers).
Pour tester votre code, démarrez ou arrêtez le service worker à l'aide des liens situés à côté de status.
![État du service worker dans le panneau "Application"](https://developer.chrome.com/docs/extensions/get-started/tutorial/debug/image/start-stop-service-worker.png?auto=format&w=845&authuser=6&hl=fr)
De plus, si vous avez modifié le code du service worker, vous pouvez cliquer sur Update (Mettre à jour) ou skipWaiting (Ignorer en attente) pour appliquer les modifications immédiatement.
![État du service worker dans le panneau "Application"](https://developer.chrome.com/docs/extensions/get-started/tutorial/debug/image/update-or-skipwaiting.png?auto=format&w=845&authuser=6&hl=fr)
Déboguer le pop-up
Maintenant que l'extension s'initialise correctement, interrompons le pop-up en mettant en commentaire les lignes en surbrillance ci-dessous:
popup.js:
...
changeColorButton.addEventListener('click', (event) => {
const color = event.target.value;
// Query the active tab before injecting the content script
chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
// Use the Scripting API to execute a script
chrome.scripting.executeScript({
target: { tabId: tabs[0].id },
args: [color],
func: setColor
});
});
});
Revenez à la page de gestion des extensions. Le bouton Erreurs réapparaît. Cliquez dessus pour afficher le nouveau journal. Il affiche le message d'erreur suivant:
Uncaught ReferenceError: tabs is not defined
![Page de gestion des extensions affichant une erreur dans une fenêtre pop-up](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/extensions-management-pag-00a0f48a76239.png?authuser=6&hl=fr)
Vous pouvez ouvrir les outils de développement du pop-up en inspectant celui-ci.
![Les outils de développement affichent une erreur dans le pop-up.](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/devtools-displaying-popup-0ed24fd80361a.png?authuser=6&hl=fr)
L'erreur tabs is undefined
indique que l'extension ne sait pas où injecter le script de contenu.
Pour corriger ce problème, appelez tabs.query()
, puis sélectionnez l'onglet actif.
Pour mettre à jour le code, cliquez sur le bouton Tout effacer dans l'angle supérieur droit, puis actualisez l'extension.
Déboguer les scripts de contenu
À présent, interrompons le script de contenu en remplaçant la variable "color" par "colors":
content.js:
...
function setColor(color) {
// There's a typo in the line below;
// ❌ colors should be ✅ color.
document.body.style.backgroundColor = color;
document.body.style.backgroundColor = colors;
}
Actualisez la page, ouvrez le pop-up et cliquez sur la case verte. Rien ne se passe.
Si vous accédez à la page de gestion des extensions, le bouton Erreurs ne s'affiche pas. En effet, seules les erreurs d'exécution console.warning
et console.error
sont enregistrées sur la page "Gestion des extensions".
Les scripts de contenu s'exécutent sur un site Web. Pour détecter ces erreurs, nous devons donc inspecter la page Web que l'extension tente de modifier:
Uncaught ReferenceError: colors is not defined
![Erreur d'extension affichée dans la console de la page Web](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/extension-error-displayed-ca9d8c6c336b.png?authuser=6&hl=fr)
Pour utiliser les outils de développement à partir du script de contenu, cliquez sur la flèche du menu déroulant à côté de top et sélectionnez l'extension.
![Erreur de référence non détectée: les couleurs ne sont pas définies.](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/uncaught-referenceerror-e5847be3a7de9.png?authuser=6&hl=fr)
L'erreur indique que colors
n'est pas défini. L'extension ne doit pas transmettre la variable correctement.
Corrigez le script injecté pour transmettre la variable de couleur dans le code.
Surveiller les requêtes réseau
Le pop-up effectue souvent toutes les requêtes réseau requises avant même que les développeurs les plus rapides puissent ouvrir les outils de développement. Pour afficher ces requêtes, actualisez le panneau "Network" (Réseau). Le pop-up est actualisé sans fermer le panneau "Outils de développement".
![Actualisez le panneau "Network" (Réseau) pour afficher les requêtes réseau pop-up](https://developer.chrome.com/static/docs/extensions/get-started/tutorial/debug/image/refresh-inside-network-p-43993068e650e.gif?authuser=6&hl=fr)
Déclarer des autorisations
Certaines API d'extension nécessitent des autorisations. Consultez l'article sur les autorisations et les API Chrome pour vous assurer qu'une extension demande les autorisations appropriées dans le fichier manifeste.
{
"name": "Broken Background Color",
...
"permissions": [
"activeTab",
"declarativeContent",
"storage"
],
...
}
Complément d'informations
Pour en savoir plus sur les outils pour les développeurs Chrome, consultez la documentation.