install.md

Installing the Lockbox Addon

Prerequisites

Before installing, you'll need the following:

• node (10.15 or higher)
• Firefox (version 67 or higher, Nightly or Developer Edition)

For locales, you'll want the following:

• compare-locales

Installing dependencies

To install the project dependencies, you can run:

npm install

Building the source code

To build the project, you can run:

npm run build

This puts all the necessary files in the dist/ directory, which you can then temporarily load into Firefox (e.g. about:debugging).

Building the extension

To build an extension .zip, you can run:

npm run package

This puts the addon bundle in the addons/ directory.

⚠️ The resulting add-on is unsigned and likely won't work on release versions of Firefox. You can flip the xpinstall.signatures.required preference on other channels accordingly.

Running the extension

To run the extension in Firefox, you can run:

npm run run -- -f nightly

This will automatically create a fresh new user profile that will not persist between runs. This means the data will be lost every time.

Running the extension with a persistent profile

To run the extension with a profile that persists between runs, you can create a new profile by browsing to about:profiles.

Once you have a new profile created (no matter the location), you can tell jpm (via npm) to run using that profile and not to copy the profile temporarily so that any changes (e.g. adding new entries) will be saved:

npm run run -- -p PROFILE --keep-profile-changes

The PROFILE value may be a profile name or the path to the profile.

Now, when you run using this profile, any data or settings you make to the browser itself or in Lockwise will be available for future runs.

Setting npm run flags

To specify flags for run to use regularly, use npm config set webext_runflags:

npm config set webext_runflags="-f nightly -p PROFILE --keep-profile-changes"

This way if you want to always test locally using an existing profile (with example data) using Firefox Nightly, you can just run (without adding flags):

npm run run

Running the extension with file watchers

To run the extension with reloading on file change:

npm run watch

This command will run the extension in Firefox. Additionally, it will start watch processes that will do the following on any file change:

• run JS and CSS linting
• rebuild the extension
• reload the extension in the browser

Note that you will need to set webext_runflags to specify flags for running Firefox, as this command does not accept any options.

Testing the extension

There are two forms of autmomated testing present: unit (test individual classes as much in isolation to everything else -- including the browser internals) and integration.

To run the unit tests, you can run:

npm run test

or simply

npm test

This runs tests using Firefox, but wholly as "web content" (what most web pages are).

To run the integration tests, you can run:

npm run integration

This drives Firefox via Selenium, driving an instance of Firefox with this addon installed.

By default, it searches for which Firefox by searching for one of the following channels (in this order):

• Nightly
• Aurora (Selenium's codename for Developer Edition)
• Beta
• Release

You can tell it which Firefox to use by setting the LOCKBOX_FIREFOX_BINARY environment variable -- either as one of the channel names or the full path to the firefox binary:

LOCKBOX_FIREFOX_BINARY=beta npm run integration

By default, the integration tests are NOT run in headless mode -- each test will result in a Firefox window opening when it starts and closing when it ends. You can run the integration tests in headless mode by setting the LOCKBOX_FIREFOX_HEADLESS environment variable to 1:

LOCKBOX_FIREFOX_HEADLESS=1 npm run integration