Merge web extension experiments support to master

.babelrc

@@ -0,0 +1,16 @@
+{
+  "env": {
+    "test": {
+      "plugins": [
+        [
+          "istanbul",
+          {
+            "exclude": [
+              "test/**/*.js"
+            ]
+          }
+        ]
+      ]
+    }
+  }
+}

.circleci/config.yml

@@ -4,49 +4,86 @@ jobs:
     docker:
       - image: circleci/node:latest-browsers
         environment:
-          FIREFOX_BINARY: /home/circleci/checkout/firefox/firefox-bin
+          FIREFOX_BIN: /home/circleci/checkout/firefox-release/firefox-bin
+          FIREFOX_AURORA_BIN: /home/circleci/checkout/firefox-beta/firefox-bin
+          FIREFOX_DEVELOPER_BIN: /home/circleci/checkout/firefox-devedition/firefox-bin
+          FIREFOX_NIGHTLY_BIN: /home/circleci/checkout/firefox-nightly/firefox-bin
 
     working_directory: ~/checkout
 
     steps:
       - checkout
 
-      # Download and cache dependencies
+      # Download and cache dependencies (update the cache keys to force a newer version)
       - restore_cache:
           keys:
-          - v1-dependencies-{{ checksum "package.json" }}
-          # fallback to using the latest cache if no exact match is found
-          - v1-dependencies-
+          - dependencies-and-browsers-{{ checksum "package.json" }}-20180831
 
-      - run: npm install
+      - run:
+          name: Install dependencies
+          command: npm install
 
       - run:
-          name:  Get nightly
+          name:  Install different versions of Firefox
           command: |
-            if [ -d ./firefox ]; then
-              echo "firefox dir exists, must be from cache"
-            else
-              ./node_modules/.bin/get-firefox -b nightly -p linux -e
-              ls ./firefox/firefox-bin
-            fi
+            [ ! -d "./firefox-release" ] && npx get-firefox -b release -p linux -e && mv ./firefox ./firefox-release || true
+            [ ! -d "./firefox-beta" ] && npx get-firefox -b beta -p linux -e && mv ./firefox ./firefox-beta || true
+            [ ! -d "./firefox-devedition" ] && npx get-firefox -b devedition -p linux -e && mv ./firefox ./firefox-devedition || true
+            [ ! -d "./firefox-nightly" ] && npx get-firefox -b nightly -p linux -e && mv ./firefox ./firefox-nightly || true
+            # Prevent any tests from using the default installed version of Firefox
+            sudo rm /usr/bin/firefox || true
 
       - save_cache:
           paths:
             - node_modules
-            - firefox
-          key: v1-dependencies-{{ checksum "package.json" }}
+            - firefox-nightly
+            - firefox-devedition
+            - firefox-beta
+            - firefox-release
+            - firefox-unbranded-release
+          key: dependencies-and-browsers-{{ checksum "package.json" }}-20180831
+
+      - run:
+          name: Reveal which Firefox versions are installed
+          command: |
+            echo "Versions of Firefox installed:"
+            ./firefox-release/firefox-bin -v
+            ./firefox-beta/firefox-bin -v
+            ./firefox-devedition/firefox-bin -v
+            ./firefox-nightly/firefox-bin -v
 
       - run:
           name: Lint
-          command: npm run eslint
+          command: npm run lint
 
       - run:
-          name: Build .XPI
+          name: Build add-on
           command: npm run build
 
+      - store_artifacts:
+          path: "dist"
+          destination: "dist"
+
       - run:
-          name: Functional tests
-          command: npm run test
+          name: Unit tests
+          command: npm run test:unit
+
+      # Needs signed add-on to work on branded releases
+      #- run:
+      #    name: Functional tests with Firefox Release
+      #    command: FIREFOX_BINARY=/home/circleci/checkout/firefox-release/firefox-bin npm run test:func && mkdir test/results/logs-release && mv test/results/logs/* test/results/logs-release/
+      #- run:
+      #    name: Functional tests with Firefox Beta
+      #    command: FIREFOX_BINARY=/home/circleci/checkout/firefox-beta/firefox-bin npm run test:func && mkdir test/results/logs-beta && mv test/results/logs/* test/results/logs-beta/
+
+      - run:
+          name: Functional tests with Firefox Developer Edition
+          command: FIREFOX_BINARY=/home/circleci/checkout/firefox-devedition/firefox-bin npm run test:func && mkdir test/results/logs-devedition && mv test/results/logs/* test/results/logs-devedition/
+
+      - run:
+          name: Functional tests with Firefox Nightly
+          command: FIREFOX_BINARY=/home/circleci/checkout/firefox-nightly/firefox-bin npm run test:func && mkdir test/results/logs-nightly && mv test/results/logs/* test/results/logs-nightly/
 
       - store_artifacts:
-          path: "dist"
+          path: "test/results"
+          destination: "test/results"

.circleci/reports/.gitignore

@@ -0,0 +1,2 @@
+*
+!*.gitignore

.eslintignore

@@ -1,12 +1,17 @@
 # do not lint/format generated artifacts
-dist
+test/results/
+dist/
 package-lock.json
+# do not lint/format bundled util libraries
+src/privileged/prefs/api.js
+src/privileged/prefs/schema.json
+src/privileged/study/api.js
+src/privileged/study/schema.json
 # makes sure that eslintrc.js gets linted/formatted
 !.eslintrc.js
-# do not lint/format bundled util libraries (PioneerUtils.jsm is included for Pioneer Shield studies only; eventually it will be merged with StudyUtils.jsm)
-addon/StudyUtils.jsm
-addon/PioneerUtils.jsm
-# for circleCI; don't lint/format code in the Firefox directory
-firefox
+# don't lint/format code the directory where get-firefox stores the Firefox binaries
+/firefox-*
 # don't lint/format package.json since npm install formats it differently by default
 package.json
+# don't lint node_modules
+node_modules

.eslintrc.js

@@ -2,11 +2,27 @@
 
 "use strict";
 
-/* All Mozilla specific rules and enviroments at:
- * http://firefox-source-docs.mozilla.org/tools/lint/linters/eslint-plugin-mozilla.html
- */
+// All Mozilla specific rules and environments at:
+// http://firefox-source-docs.mozilla.org/tools/lint/linters/eslint-plugin-mozilla.html
 
 module.exports = {
+  env: {
+    es6: true,
+  },
+  extends: [
+    "eslint:recommended",
+    // list of rules at: https://dxr.mozilla.org/mozilla-central/source/tools/lint/eslint/eslint-plugin-mozilla/lib/configs/recommended.js
+    "plugin:mozilla/recommended",
+  ],
+  overrides: [
+    {
+      files: "src/**",
+      env: {
+        browser: true,
+        webextensions: true,
+      },
+    },
+  ],
   parserOptions: {
     ecmaVersion: 8,
     sourceType: "module",
@@ -15,32 +31,33 @@ module.exports = {
       experimentalObjectRestSpread: true,
     },
   },
-  env: {
-    es6: true,
-    // 'browser-window': false
-  },
-  extends: [
-    "eslint:recommended",
-    /* list of rules at:
-     * https://dxr.mozilla.org/mozilla-central/source/tools/lint/eslint/eslint-plugin-mozilla/lib/configs/recommended.js
-     */
-    "plugin:mozilla/recommended",
-  ],
-
   plugins: ["json", "mozilla"],
-
+  root: true,
   rules: {
     "babel/new-cap": "off",
+    "mozilla/no-aArgs": "warn",
+    "mozilla/balanced-listeners": "off",
     "comma-dangle": ["error", "always-multiline"],
     eqeqeq: "error",
     indent: ["warn", 2, { SwitchCase: 1 }],
-    "mozilla/no-aArgs": "warn",
-    "mozilla/balanced-listeners": "off",
+    "max-len": [
+      "warn",
+      {
+        code: 100,
+        ignoreComments: true,
+        ignoreTrailingComments: true,
+        ignoreUrls: true,
+        ignoreStrings: true,
+        ignoreTemplateLiterals: true,
+      },
+    ],
     "no-console": "warn",
     "no-shadow": "error",
     "no-unused-vars": "error",
+    "no-var": "error",
     "prefer-const": "warn",
     "prefer-spread": "error",
     semi: ["error", "always"],
+    "valid-jsdoc": "warn",
   },
 };

.gitignore

@@ -1,6 +1,4 @@
-chrome.manifest
-install.rdf
-*.xpi
-node_modules
-addon/StudyUtils.jsm
-addon/PioneerUtils.jsm
+dist/*
+node_modules/
+.env
+/firefox-*

README.md

@@ -1,41 +1,74 @@
-# Shield Study Embedded Web Extension Template
+# Shield Studies Add-On Template
 
 [![CircleCI badge](https://img.shields.io/circleci/project/github/mozilla/shield-studies-addon-template/master.svg?label=CircleCI)](https://circleci.com/gh/mozilla/shield-studies-addon-template/)
+[![Coverage Status](https://coveralls.io/repos/github/mozilla/shield-studies-addon-template/badge.svg)](https://coveralls.io/github/mozilla/shield-studies-addon-template)
 
-## Important notice
+## About This Repository
+
+This repository is intended as an example repository containing templates and good
+practices for creating a [Shield Study](https://wiki.mozilla.org/Firefox/Shield/Shield_Studies) add-on for Firefox.
 
-### We are moving to Web Extension Experiments
+### Important notice
 
-In an effort to remove the necessity of creating legacy add-ons for Shield studies, we are working on [supporting a pure Web Extension Experiment workflow in this template](https://github.com/mozilla/shield-studies-addon-template/issues/53) with a new version, v5, of the [Shield utilities](https://github.com/mozilla/shield-studies-addon-utils/). Support for these workflows is not yet stable. In the meantime, **we do not recommend using this v4 template**.
+We just started [supporting a pure Web Extension Experiment workflow in this template](https://github.com/mozilla/shield-studies-addon-template/issues/53) with a new version, v5, of the [Shield utilities](https://github.com/mozilla/shield-studies-addon-utils/).
+Even though support for these workflows are yet to pass official QA review, **we do not recommend using the old template (for creating legacy boostrapped add-ons using Shield Utils v4) of this template**. Creating a legacy boostrapped add-on with the outdated master branch will likely result in a broken Shield study add-on in recent versions of Firefox.
 
 Instead, we recommend that you:
+
 * build your study as a WEE ([Web Extension Experiment](https://firefox-source-docs.mozilla.org/toolkit/components/extensions/webextensions/index.html))
-* help us test the requisite [experimental Shield API(s)](https://github.com/mozilla/shield-studies-addon-utils/)
+* help us test the requisite [new Shield Web Extension API(s)](https://github.com/mozilla/shield-studies-addon-utils/)
+
+Example Shield add-ons using the experimental Shield API(s):
 
-Example Shield add-ons (implemented as WEEs) using the experimental Shield API(s):
-* https://github.com/mozilla/shield-studies-addon-utils/blob/develop/examples/small-study
-* https://github.com/mozilla/shield-cloudstorage
+* This template
+* <https://github.com/mozilla/shield-studies-addon-utils/tree/master/examples/small-study>
+* <https://github.com/motin/taar-experiment-v3-shield-study>
+* <https://github.com/motin/dataleak-pioneer-shield-study>
+* <https://github.com/mozilla/shield-cloudstorage>
 
 Chat with us: #shield on Slack about the latest progress and how to help us move faster away from legacy add-ons.
 
-## About This Repository
+### Aims
+
+The aim is to bring together tools and services we've used on other Shield Study add-ons into a template/example repository, so that new projects can come
+along and get infrastructure together, and be up and running with code, test suites, coverage etc quickly.
+
+Using this template will get you these things:
 
-**Note**: This contains an example [Shield Study](https://wiki.mozilla.org/Firefox/Shield/Shield_Studies) Legacy Add-on. Use this as a template for yours.
+* [Shield Utils](https://github.com/mozilla/shield-studies-addon-utils/) integration and example usage
+* Functional tests
+* Unit tests
+* Continuous integration testing against Release, Beta, Dev Edition and Nightly (via Circle CI)
+* [Example web extension experiment implementing custom ui using privileged code](./src/privileged/introductionNotificationBar/)
+* Linting
+* Partial code coverage (specific files)
 
-(Note: Make this README reflect your study).
+Bonus:
 
-Goal: Determine which if any TOOLBAR BUTTONS DESIGNS is the most enticing to the user.
+* Consistent package.json (fixpack) and package-lock.json
+* Addon-linter
+* Runs nsp during lint
+
+### Documentation
+
+It is intended that all parts of this repository have at least outline
+documentation. If you find any parts that are missing, please file an issue or
+create a PR.
+
+### Using this template
+
+1. Fork this repository, rename it to reflect your study. Make the repo end with `-shield-study`
+2. Make this README reflect your study (including removing all of this `About This Repository` section whilst keeping `Seeing the add-on in action` and below)
+3. Remove irrelevant example code
+4. Build your study add-on and make the docs reflect your study
+5. File issues/PRs against https://github.com/mozilla/shield-studies-addon-template/ when you come across things to improve in the template
 
 ## Seeing the add-on in action
 
 See [TESTPLAN.md](./docs/TESTPLAN.md) for more details on how to get the add-on installed and tested.
 
 ## Data Collected / Telemetry Pings
 
-Measure:
-
-* Button (BrowserAction) usage.
-
 See [TELEMETRY.md](./docs/TELEMETRY.md) for more details on what pings are sent by this add-on.
 
 ## Analyzing data