Las extensiones pueden acceder a las mismas herramientas para desarrolladores de Chrome que las páginas web. Para convertirte en un experto en la depuración de extensiones, debes saber cómo localizar los registros y errores de los diferentes componentes de la extensión. En este instructivo, se proporcionan técnicas fundamentales para depurar tu extensión.
Antes de comenzar
En esta guía, se da por sentado que tienes experiencia básica en desarrollo web. Te recomendamos que leas Conceptos básicos de desarrollo para obtener una introducción al flujo de trabajo de desarrollo de extensiones. En Diseña la interfaz de usuario, se brinda una introducción a los elementos de la interfaz de usuario disponibles en las extensiones.
Rompe la extensión
En este instructivo, se desglosa un componente de la extensión a la vez y, luego, se muestra cómo solucionarlo. Recuerda deshacer los errores ingresados en una sección antes de pasar a la siguiente. Primero, descarga la muestra de colores dañados en GitHub.
Cómo depurar el manifiesto
Primero, dividimos el archivo de manifiesto cambiando la clave "version" a "versions":
manifest.json:
{
"name": "Broken Background Color",
"version": "1.0",
"versions": "1.0",
"description": "Fix an Extension!",
...
}
Ahora intentemos cargar la extensión de forma local. Verás un cuadro de diálogo de error que indicará el problema:
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.
Cuando una clave de manifiesto no es válida, la extensión no se carga, pero Chrome te indica cómo solucionar el problema.
Deshaz ese cambio e ingresa un permiso no válido para ver qué sucede.
Cambia el permiso "activeTab" a minúscula "activetab":
manifest.json:
{
...
"permissions": ["activeTab", "scripting", "storage"],
"permissions": ["activetab", "scripting", "storage"],
...
}
Guarda la extensión y vuelve a cargarla. Esta vez, debería cargarse correctamente. En la página Administración de extensiones, verás tres botones: Detalles, Quitar y Errores. La etiqueta del botón Errors se pone de color rojo cuando hay un error. Haz clic en el botón Errores para ver el siguiente error:
Permission 'activetab' is unknown or URL pattern is malformed.
Antes de continuar, vuelve a cambiar el permiso, haz clic en Borrar todo en la esquina superior derecha para borrar los registros y vuelve a cargar la extensión.
Depura el service worker
Ubica registros
El service worker establece el color predeterminado para Storage y lo registra en la consola. Para ver este registro, seleccione el vínculo azul junto a Inspeccionar vistas para abrir el panel de Herramientas para desarrolladores de Chrome.
Ubica errores
Analicemos el service worker. Cambia onInstalled a oninstalled en minúscula:
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.');
});
});
Actualiza y haz clic en Errors para ver el registro de errores. El primer error te avisa que el service worker no se pudo registrar. Esto significa que se produjo un error durante la iniciación:
Service worker registration failed. Status code: 15.
El error real viene después:
Uncaught TypeError: Cannot read properties of undefined (reading 'addListener')
Deshaz el error que presentamos, haz clic en Borrar todo en la esquina superior derecha y vuelve a cargar la extensión.
Verifica el estado del service worker
Puedes identificar cuándo se activa el service worker para realizar tareas; para ello, sigue estos pasos:
- Copia el ID de la extensión que se encuentra arriba de "Inspeccionar vistas".
El ID de extensión en la página Administración de extensiones. - Abre el archivo de manifiesto en el navegador. Por ejemplo:
text chrome-extension://YOUR_EXTENSION_ID/manifest.json - Inspecciona el archivo.
- Ve al panel Application.
- Ve al panel Service Workers.
Para probar el código, inicia o detén el service worker. Para ello, usa los vínculos que aparecen junto a status.
Además, si modificaste el código del service worker, puedes hacer clic en Update, o bien en skipWaiting para aplicar los cambios de inmediato.
Cómo depurar la ventana emergente
Ahora que la extensión se inicializa correctamente, dividamos la ventana emergente y marquemos las siguientes líneas destacadas:
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
});
});
});
Regresa a la página Administración de extensiones. Volverá a aparecer el botón Errores. Haz clic en él para ver el registro nuevo. Se muestra el siguiente mensaje de error:
Uncaught ReferenceError: tabs is not defined
Puedes abrir las Herramientas para desarrolladores de la ventana emergente inspeccionando la ventana emergente.
El error tabs is undefined indica que la extensión no sabe dónde insertar la secuencia de comandos de contenido.
Para corregir esto, llama a tabs.query() y, luego, selecciona la pestaña activa.
Para actualizar el código, haz clic en el botón Clear all en la esquina superior derecha y, luego, vuelve a cargar la extensión.
Cómo depurar secuencias de comandos de contenido
Ahora, divulguemos la secuencia de comandos de contenido cambiando la variable "color" a "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;
}
Actualiza la página, abre la ventana emergente y haz clic en el cuadro verde. No pasa nada.
Si vas a la página Administración de extensiones, el botón Errores no aparece. Esto se debe a que solo los errores de tiempo de ejecución, console.warning y
console.error, se registran en la página Administración de extensiones.
Las secuencias de comandos de contenido se ejecutan dentro de un sitio web. Por lo tanto, para encontrar estos errores, debemos inspeccionar la página web que la extensión intenta modificar:
Uncaught ReferenceError: colors is not defined
Para usar Herramientas para desarrolladores desde la secuencia de comandos de contenido, haz clic en la flecha del menú desplegable junto a top y selecciona la extensión.
El error indica que no se definió colors. La extensión no debe pasar la variable correctamente.
Corrige la secuencia de comandos insertada para pasar la variable de color al código.
Supervisa las solicitudes de red
A menudo, la ventana emergente realiza todas las solicitudes de red necesarias antes de que incluso los desarrolladores más veloces puedan abrir Herramientas para desarrolladores. Para ver estas solicitudes, actualízalas desde el panel de red. Vuelve a cargar la ventana emergente sin cerrar el panel de Herramientas para desarrolladores.
Cómo declarar permisos
Algunas APIs de extensiones requieren permisos. Consulta el artículo sobre permisos y las APIs de Chrome para asegurarte de que una extensión solicite los permisos correctos en el manifiesto.
{
"name": "Broken Background Color",
...
"permissions": [
"activeTab",
"declarativeContent",
"storage"
],
...
}
Lecturas adicionales
Lee la documentación para obtener más información sobre Herramientas para desarrolladores de Chrome.