Debugging extensions
Published on • Updated on
Extensions are able to leverage the same debugging benefits Chrome DevTools provides for web pages, but they carry unique behavior properties. Becoming a master extension debugger requires an understanding of these behaviors, how extension components work with each other, and where to corner bugs. This tutorial gives developers a basic understanding of debugging extensions.
Locate the logs
Extensions are made of many different components, and these components have individual responsibilities. Download a broken extension here to begin locating error logs for different extension components.
Background script
Navigate to the chrome extensions management page at chrome://extensions
and ensure developer mode is on. Click the Load Unpacked button and select the broken extension directory. After the extension is loaded, it should have three buttons: Details, Remove and Errors in red letters.
![Image displaying error button on extension management page](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/NPUXnZrLSG6T6zTCmbxj.png?auto=format)
Click the Errors button to view the error log. The extensions system has found an issue in the background script.
Uncaught TypeError: Cannot read property 'addListener' of undefined
![Extensions Management Page displaying background script error](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/5UNQ4gp40qQZIwOLTzxA.png?auto=format)
Additionally, the Chrome DevTools panel can be opened for the background script by selecting the blue link next to Inspect views.
![DevTools displaying background script error](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/GvIXA3o7JvOxUg9BV12z.png?auto=format)
Return to the code.
chrome.runtime.oninstalled.addListener(function() {
chrome.storage.sync.set({color: '#3aa757'}, function() {
console.log('The color is green.');
});
chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
chrome.declarativeContent.onPageChanged.addRules([{
conditions: [new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostEquals: 'developer.chrome.com'},
})],
actions: [new chrome.declarativeContent.ShowPageAction()]
}]);
});
});
The background script is attempting to listen for the onInstalled
event, but the property name requires an upper case "I". Update the code to reflect the correct call, click the Clear all button in the upper right hand corner, then reload the extension.
Popup
Now that the extension initializes correctly, other components can be tested. Refresh this page, or open a new tab and navigate to any page on developer.chrome.com, open the popup and click the green square. And... nothing happens.
Navigate back to the Extensions Management Page, the Errors button has reappeared. Click it to view the new log.
Uncaught ReferenceError: tabs is not defined
![Extensions Management Page displaying popup error](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/ygCnLz4Dst4mktOQhj4S.png?auto=format)
Popup errors can also be viewed by inspecting the popup.
![DevTools displaying popup error](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/PTfS6FEsE6vkbtDVMcsM.png?auto=format)
The error, tabs is undefined
, says the extension doesn't know where to inject the content script. This can be corrected by calling the tabs.query()
method, then selecting the active tab.
let changeColor = document.getElementById('changeColor');
chrome.storage.sync.get(['color'], ({color}) => {
changeColor.style.backgroundColor = color;
changeColor.setAttribute('value', color);
});
changeColor.addEventListener('click', () =>
chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
chrome.scripting.executeScript(
tabs[0].id,
{ function: setColor });
});
);
async function setColor() {
let {color} = await chrome.storage.sync.get(['color']);
document.body.style.backgroundColor = color;
};
Update the code, click the Clear all button in the upper right hand corner, and then reload the extension.
Content script
Refresh the page, open the popup and click the green box. And... nope, the background still hasn't changed colors! Navigate back to the Extensions Management Page and... there is no Errors button. The likely culprit is the content script, which runs inside the web page.
Open the DevTools panel of the web page the extension is trying to alter.
![Extension error displayed in web page console](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/q6cdFK0h7JEfaQKUMDg0.png?auto=format)
Only runtime errors, console.warning
and console.error
will be recorded on the Extensions Management Page.
To use DevTools from within the content script, click the dropdown arrow next to top and select the extension.
![Uncaught ReferenceError: tabs is not defined](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/uo8osbvVkG5HcJS00bAR.png?auto=format)
The error says color
is not defined. The extension must not be passing the variable correctly. Correct the injected script to pass the color variable into the code.
document.body.style.backgroundColor = "' + color + '";
Extension tabs
Logs for extension pages displayed as a tab, such as override pages and full-page options, can be found in the web page console and on the extensions management page.
Monitor network requests
The popup will often make all of the required network requests before even the speediest of developers can open DevTools. To view these requests, refresh from inside the network panel. It will reload the popup without closing the DevTools panel.
![Refresh inside the network panel to view popup network requests](https://wd.imgix.net/image/BrQidfK9jaQyIHwdw91aVpkPiib2/x8knWvTA11f4j1wVoNY8.gif?auto=format)
Declare permissions
While extensions have similar capabilities as web pages they often need permission to use certain features, such as cookies, storage and Cross-Origin XMLHttpRequests. Refer to the permissions article and the available Chrome APIs to ensure an extension is requesting the correct permissions in its manifest.
{
"name": "Broken Background Color",
"version": "1.0",
"description": "Fix an Extension!",
"permissions": [
"activeTab",
"declarativeContent",
"storage"
],
"options_page": "options.html",
"background": {
"service_worker": "background.js"
},
"action": {
"default_popup": "popup.html",
"default_icon": {
"16": "images/get_started16.png",
"32": "images/get_started32.png",
"48": "images/get_started48.png",
"128": "images/get_started128.png"
}
},
"icons": {
"16": "images/get_started16.png",
"32": "images/get_started32.png",
"48": "images/get_started48.png",
"128": "images/get_started128.png"
},
"manifest_version": 3
}
Next steps
For further information on debugging extensions, watch Developing and Debugging. Learn more about Chrome Devtools by reading the documentation.
Updated on • Improve article