Software Update:Testing
From MozillaWiki
UPDATE SERVICE TESTS
Input Parameters:
- Update Service URL
- Update Service XML File
- Partial Update Patch
- Complete Update Patch
- Update Settings
- UI Features
- Workflows
1. Update Service URL:
- set app.update.url.override to use a custom update service XML file which may be deployed on your box. - test for DNS failure, 404, etc.
2. Update Service XML File:
- Formatted like so: <?xml version="1.0"?> <updates xmlns="http://www.mozilla.org/2005/app-update"> <update type="minor" version="1.1.2" extensionVersion="1.1" detailsURL="http://www.mozilla.org/products/firefox/releases/1.1/whatsnew.html" licenseURL="http://www.mozilla.org/products/firefox/releases/1.1/license.html"> <patch type="partial" URL="http://download.mozilla.org/foo/bar-partial" hashFunction="sha256" hashValue="68e656b251e67e8358bef8483ab0d51c6619f3e7a1a9f0e75838d41ff368f728" size="324344"/> <patch type="complete" URL="http://download.mozilla.org/foo/bar-complete" hashFunction="sha256" hashValue="68e656b251e67e8358bef8483ab0d51c6619f3e7a1a9f0e75838d41ff368f728" size="6243443"/> </update> .. </updates>
- <update type="minor|major" ..> implies security vs. major update, and text in the Update Wizard differs depending on what is supplied. - <update version="1.1.2" ..> is the version of the update - <update extensionVersion="1.1" ..> is the general application version targeted by extensions that are compatible with this update (used for compatibility checking) - <update detailsURL=".." ..> is the URL where users can find more information about what's new in this update. This should be user friendly, concise, and not the full release notes page, although it could be a subset of a multi-page release notes information set. - <update licenseURL=".." ..> is the URL where a HTML fragment containing a new license that must be accepted by the user before they can install this update is stored. If this is not supplied, then the user is not shown the license UI.
- <patch URL=".." ..> is the the URL where the update .mar file can be found - <patch type="partial|complete" ..> is the type of patch - partial for a binary difference patch, complete for a complete set of replacement files. - <patch size="234234" ..> is the size (in bytes) of the update .mar file. This is currently unused but should be supplied. - <patch hashFunction="sha256" ..> Hash function names are stored here: https://dxr.mozilla.org/mozilla-central/source/netwerk/base/nsICryptoHash.idl Test invalid values for hash function name - <patch hashValue=".." ..> Hash function value is computed by the build system to prevent tampering with files by hacked mirrors and to make sure we don't try and apply a patch file that was corrupted during the download process. Test valid and invalid hash values. Invalid values for partial patches should cause the update system to begin downloading the complete patch instead. If the user is monitoring the download process they will be informed fo the failure by the UI.
- There can be more than one <update> entries in a single XML file, the Update Service client should select the newest.
3. Partial Update File
- the binary difference of two versions of the application. See darin's notes for information on generating
4. Complete Update File
- the complete set of files and update commands required to install a working instance of the application. Should be completely autonomous. See darin's notes for information on generating.
5. Update Settings
- There are several preferences which control the Update Service client:
BOOLEAN - app.update.enabled Default: true
enables or disables the background update checker. UI is still available
for the user to manually check for updates (in Options or the Help menu),
this UI should also be disabled when this preference is locked by an
administrator
BOOLEAN - app.update.auto Default: true
enables background download of update .mar files, according to the
policy described by app.update.mode
INTEGER - app.update.mode Default: 1
defines the policy by which background downloads are done, and the amount
of user prompting that is required:
0 - download all update types (major/minor) without user intervention,
regardless of incompatible extensions installed (they should just be
disabled after the update restart)
1 - download all update types (major/minor) only if there are no
incompatibilities with enabled extensions, prompt with UI otherwise.
2 - download minor updates only, prompt for major updates, regardless
of whether or not all enabled extensions are compatible.
Note: The following applies to Gecko 1.9.1 / Firefox 3.5 and below
BOOLEAN - app.update.log.* Default: false
enables logging for various Update Service components, set preferences
like so:
app.update.log.ModuleName = true
Modules:
Checker, Downloader, UpdateService, General, UpdateManager,
UI:DownloadingPage, UI:CheckingPage, UI:LicensePage, etc.
Note: The following applies to Gecko 1.9.2 / Firefox 3.6 and above
BOOLEAN - app.update.log Default: false
enables logging for the Application Update Service components
WSTRING - app.update.url.manual Default: <url>
the default update service XML file URL
WSTRING - app.update.url.override Default: ""
an override value for the update service XML file URL for testing
INTEGER - app.update.timer Default: 5000
the number of milliseconds between checker update interval expiry checks
NOTE: this is NOT the time between service URL pings!
INTEGER - app.update.interval Default: 86400
the number of seconds between service XML pings. expiry of this interval
is checked with a separate timer determined by |app.update.timer|
INTEGER - app.update.nagTimer.download Default: 86400
the number of seconds after a user chooses the "Later" button in the
update available nag UI to wait before annoying them with news of the
update again.
INTEGER - app.update.nagTimer.restart Default: 1800
the number of seconds after the user chooses to Restart the browser
Later after an update has been downloaded to annoy them with a prompt
to restart.
BOOLEAN - app.update.silent Default: false
disables all notification UI for updates, does not mean that the updates
will not occur though - they will according to the other control
preferences, just without prompting the user.
BOOLEAN - app.update.showInstalledUI Default: false
disables the "Update was Successfully Installed" page for Firefox only,
since Firefox uses a start page to inform the user that they have upgraded,
Thunderbird and other non-browser apps will set this to true.
6. UI Features
- Update Wizard UI
(Help, Check for Updates...)
(Tools, Options, Advanced, Update, Check Now...)
(<background invocation>)
- Update History UI
(Tools, Options, Advanced, Update, Show Update History...)
- Update Preferences
(Tools, Options, Advanced, Update)
6. Workflows
Background Checker:
- if background checking is enabled, the application will periodically
check for updates and if it finds them take action depending on the
value of app.update.auto and app.update.mode (see above).
- if a partial patch fails to verify, the service will begin downloading
a complete update. If the complete update fails to verify, then the
service will either die silently (in the background) and will check
again in another 24 hours, or will notify the user of this failure
(in the foreground) and provide a link that the user can follow to
manually update their software immediately.
- once a patch has been downloaded and verified, the user will be
notified of this and prompted to restart the browser (they can opt out)
- this prompting is done regardless of whether or not the update
download was done in the background or if the user gave consent or not.
- the application is restarted either by the prompt UI or later, manually
by the user, and the patch application process is initiated.
- if a partial patch fails to apply, the service will notify the user
about this and tell them it will download a complete patch. It will
present a UI to track the download. The user is free to browse while
this download occurs. When the download is complete they are prompted
to restart again.
- if a complete patch fails to apply, they are shown a URL that they can
navigate to to manually update their software.
Foreground Checker:
- works the same way, except there is a UI present on screen for each
stage of the process. some heuristics relating to user notification
and the content of each stage of the wizard vary depending on whether
or not the system was invoked by the user or the background checker.
Extension Update Across Major Updates
To test Extension Update across major application updates with a nightly build, you need:
- some extensions (installed)
- preferably some test extensions that you can hand edit
Open the file compatibility.ini in your profile and change the line that reads something like:
LastVersion=1.0+_2005071915/1.8b4_2005071915
to have a number different than the one shown, e.g.:
LastVersion=1.0+_2005071915/1.8b4_2005071900
Now, open prefs.js in your profile and:
add:
user_pref("app.extensions.version", "5.0");
(or some other number much larger than the current version)
and make sure there is no line like this:
user_pref("extensions.lastVersion", "5.0"); or similar.
Now start Firefox. A wizard UI should appear and allow you to check for updates to your incompatible extensions.
Functionality
When the Firefox starts, it detects the update condition that you created by editing the files as described above. It collects a list of addons that are incompatible with the new running instance, and then:
- checks for VersionInfo updates to each of the items in the list... a VersionInfo update is a remove compatibility update provided by the author of the addon through AMO or their custom update.rdf file that says that the existing installed version of the addon is in fact compatible with the new version of Firefox, and requires no new XPI download/install
- after the VersionInfo check reduces the incompatibility list somewhat, displays a list of addons that are still incompatible and will need to be updated to still be functional.
- checks for newer versions of the said addons.
- when it discovers the updates that are available, shows them to the user and gives them the ability to download and install them now.
- downloads and installs the selected updates
- shows information to the user about any errors encountered in this process, also, shows information about items that are still incompatible (no updates found), and gives the user the ability to opt into auto update checking if the user has previously disabled extension auto update checking.
