Chrome extension update flow

Question

I am starting with chrome extension development and have a couple of questions regarding extension install/update flow and testing during the development :

1. What happens with the background script after extension update, does chrome perform background script reload ?
2. Are content scripts detached from background script after extension update ?
3. If there's an onInstalled event handler in background script, what happens with that event handler when chrome updates extension(is this event handler detached, and when update finishes, the new handler is attached and then executed or some other flow is exercised) ?
4. Is there a way to simulate update process during development in order to debug events that happen during the update process, for example to host extension on some local server and update from there ?
5. where to search for documentation on topics like this and similar, is the chromium source code the right place or at least the starting point ?

Thanks!

Answer 1

1. What happens with the background script after extension update, does Chrome perform background script reload?

The behavior depends on whether you have a handler to chrome.runtime.onUpdateAvailable event registered and whether your extension has a persistent background page or event page.

• If you have a persistent background page:
  • If you handle this event and call chrome.runtime.reload(), the extension is unloaded and then updated before being loaded again.
  • If you handle this event and do not call chrome.runtime.reload(), then the update will only apply when the extension is next reloaded - likely the next full browser restart.
  • If you do not handle this event at all, the extension will be unloaded immediately to be updated.
• If you have a non-persistent Event page:
  • If you handle this event and call chrome.runtime.reload(), the extension is updated before being loaded again.
  • If you do not call chrome.runtime.reload(), or do not handle the event at all, Chrome will update the extension when the Event page next gets unloaded.

There is no way to programmatically prevent the update once the background page gets unloaded for whatever reason.

2. Are content scripts detached from background script after extension update?

Yes, and it's not pretty. They enter an "orphaned" state when using Chrome API gives inconsistent errors (some do nothing, some trigger exceptions), but are still running — for example, any DOM event listeners will still trigger.

As such, if you want the content scripts to work immediately again, your job is to:

• Inject scripts programmatically in existing tabs, without making an assumption that it did not execute before: cleanup first if necessary.
• Make sure orphaned copies stop executing: either by noticing in the old copy that it's orphaned, or by broadcasting a DOM event from the new copy.

Important note about WebExtensions: Firefox, unlike Chrome, always reinjects content scripts on load into pages that match manifest entries. Make sure to take that into account.

There are a few question that cover this; for example:

• Sending message from a background script to a content script, then to a injected script (See addendum to the answer)
• How to properly handle chrome extension updates from content scripts
• Chrome extension content script re-injection after upgrade or install

3. If there's an onInstalled event handler in background script, what happens with that event handler when chrome updates extension (is this event handler detached, and when update finishes, the new handler is attached and then executed or some other flow is exercised)?

Since an update can only happen while the background page is unloaded, there is no complex logic; it will simply fire on first load of the extension afterwards with details.reason == "update". Be sure to register the handler synchronously on script load (e.g. in top level code), or else you may miss the event — normally this only concerns Event pages, but I suspect it's also important here.

4. Is there a way to simulate update process during development in order to debug events that happen during the update process, for example to host extension on some local server and update from there?

Sadly, this is no longer possible to the best of my knowledge, unless you can use Enterprise Policy install. Your best bet is to have an extension in CWS that's published as Private.

To a certain extent, pressing "Reload" after making some changes to an unpacked extension simulates what happens during the update - with the exception of onInstalled event.

5. Where to search for documentation on topics like this and similar, is the chromium source code the right place or at least the starting point?

Well.. For detailed questions Chromium code is, of course, the authoritative source. You should search StackOverflow as well, as there's quite a body of knowledge amassed here already. Finally, the official docs provide a lot of information, even if it's not immediately evident - the chrome.runtime API docs, for example.