Develop

Test permission requests

Your extension may contain two types of permission request: install time and runtime permission requests. This page explains how you can test the way your users will see requests for these permissions.

Permission grant behavior during testing

When you’re testing with an unpackaged extension, using either about:debugging or web-ext, install time and runtime permissions are handled as follows:

  • install time permission requests are granted silently. You don’t see the permission warnings users would.
  • runtime permission requests display the door hanger request as normal. These permissions remain in place until they are revoked programmatically by the extension, the extension is removed using about:debugging, or Firefox restart.

Observe or verify install time permission requests

You follow different processes depending on whether you want to observe the permissions requests associated with an installation or an upgrade.

Permission requests for extension installation

To view the install time permission warnings users see when installing your extension and retest runtime permission requests, install the extension from its *.xpi or *.zip file.

To do this with an unsigned *.xpi or *.zip file you need to:

Then install the extension using Install Add-on From File in the Add-on manager (about:addons). As the extension installs, the request to grant the install-time permissions displays, similar to this:

installing unpacked extension

Note that the caution message relates to this being an unsigned extension; this message isn’t displayed during installation from addons.mozilla.org.

Permission requests for extension upgrade

For details on how to deliver web extension updates when self-hosting your extension, see Updates.

To view the install time permission warnings users see when Firefox upgrades your extension and retest runtime permission requests, you install the extension from its .xpi file posted on an HTTP or HTTPS server.

You can use an HTTP server (such as a simple Python localhost server) or an HTTPS server. However, your HTTPS server must have a verifiable certificate, one that Firefox can auto-accept; you cannot use a self-signed certificate. If you want to test from an HTTPS server but don’t have one, GitHub pages are an option you can use.

To perform the test you’ll need to:

  • determine the address of the HTTP or HTTPS server where you can host files.
  • use the manifest.json browser_specific_settings key to:
    • give your extension an ID, if you’ve not done so already.
    • define the update URL where you’ll host your updates manifest. For example:
1
2
3
4
5
6
7
"browser_specific_settings": {
  "gecko": {
    "strict_min_version": "54.0a1",
    "update_url": "https://your-account.github.io/webextensions/upgrade.json",
    "id": "test@your-address.com"
  }
},
  • if necessary, create a package containing your original extension.
  • update your extension and add details of the new permissions required to the manifest.json file, not forgetting to update the version number. Create a package containing your updated extension.

If the packages were generated with .zip extensions change them to .xpi, otherwise your browser may try to download rather than install the extension.

  • create the updates manifest with details of both extension versions, which should be similar to this:
1
2
3
4
5
6
7
"browser_specific_settings": {
  "gecko": {
    "strict_min_version": "54.0a1",
    "update_url": "https://your-account.github.io/webextensions/upgrade.json",
    "id": "test@your-address.com"
  }
},
  • upload the two extension packages and the updates manifest to your HTTP or HTTPS server.
  • run the Nightly or Developer Edition versions of Firefox.
  • in about:config:

    • set the preference xpinstall.signatures.required to false.
    • If you’re using Nightly and hosting your update on an HTTP server create and set extensions.checkUpdateSecurity and extensions.install.requireSecureOrigin preferences to false. To do this:
      • enter the preference name in the search box.
      • click Add.
        add preference
      • toggle the preference to set it to false.
        toggle preferences
  • open the link to the first XPI file to install it.
  • open about:addons, click the gear icon, and click Check for Updates.
  • you’ll get a permission warnings prompt, similar to the one below, detailing the additional permissions requested:

permissions prompt

If the upgrade doesn’t happen, look for addons.update-checker logs in the Browser Console. Any errors encountered during the upgrade process will be reported in the log.

Retest runtime permission grants

To retest your extension’s runtime permission grants and its post-install behavior you’ve two choices:

  • remove the extension using about:debugging and reinstall it, or Firefox restart.

remove extension from debugging

You can then rerun the extension and any runtime permission requests will be displayed as if the extension was being run for the first time.