Add the ability to load and test web extensions.

Validate this change by writing a few simple tests that verify that
some APIs on browser.runtime behave as expected.

Author: Elijah Sawyers

docs/writing-tests/testharness.md

@@ -199,7 +199,35 @@ dedicated worker tests and shared worker
 tests](testharness-api.html#determining-when-all-tests-are-complete), it is
 automatically invoked for tests defined using the "multi-global" pattern.
 
-## Other features of `.window.js`, `.worker.js` and `.any.js`
+## Extension tests (`.extension.js`)
+
+Create a JavaScript file whose name ends in `.extension.js` to have the necessary HTML boilerplate
+generated for you at `.extension.html`.
+
+Extension tests leverage the `browser.test` API rather than interacting with the `testharness.js`
+framework directly.
+
+For example, one could write a test for `browser.runtime.getURL()` by creating a
+`web-extensions/browser.runtime.extension.js` file as follows:
+
+```js
+runTestsWithWebExtension("/resources/runtime/")
+// ==> this method assumes that the extension resources (manifest, scripts, etc.) exist at the path
+```
+
+And by creating a `web-extensions/resources/runtime/background.js` file as follows:
+
+```js
+browser.test.runTests([
+  function getURLWithNoParameter() {
+    browser.test.assertThrows(() => browser.runtime.getURL())
+  }
+])
+```
+
+This test could then be run from `web-extensions/browser.runtime.extension.html`.
+
+## Other features of `.window.js`, `.worker.js`, `.any.js` and `.extension.js`
 
 ### Specifying a test title
 

resources/testdriver.js

@@ -1497,6 +1497,42 @@
          */
         set_protected_audience_k_anonymity: function(owner, name, hashes, context = null) {
             return window.test_driver_internal.set_protected_audience_k_anonymity(owner, name, hashes, context);
+        },
+
+         /**
+         * Loads a WebExtension.
+         *
+         * Matches the `Load Web Extension
+         * <https://github.com/w3c/webextensions/blob/main/specification/webdriver-classic.bs>`_
+         * WebDriver command.
+         *
+         * @param {String} type - A type such as "path", "archivePath", or "base64".
+         *
+         * @param {String} path - The path to the extension's resources if type "path" or "archivePath" is specified.
+         *
+         * @param {String} value - The base64 encoded value of the extension's resources if type "base64" is specified.
+         *
+         * @returns {Promise} Returns the extension identifier as defined in the spec.
+         *                    Rejected if the extension fails to load.
+         */
+        install_web_extension: function(path) {
+            return window.test_driver_internal.install_web_extension(path);
+        },
+
+        /**
+         * Unloads a WebExtension.
+         *
+         * Matches the `Unload Web Extension
+         * <https://github.com/w3c/webextensions/blob/main/specification/webdriver-classic.bs>`_
+         * WebDriver command.
+         *
+         * @param {String} extension_id - The extension idetifier.
+         *
+         * @returns {Promise} Fulfilled after the extension has been removed.
+         *                    Rejected in case the WebDriver command errors out.
+         */
+        uninstall_web_extension: function(extension) {
+            return window.test_driver_internal.uninstall_web_extension(extension);
         }
     };
 

resources/web-extensions-helper.js

@@ -0,0 +1,42 @@
+// testharness file with WebExtensions utilities
+
+/**
+ * Loads the WebExtension at the path specified and runs the tests defined in the extension's resources.
+ * Listens to messages sent from the user agent and converts the `browser.test` assertions
+ * into testharness.js assertions.
+ *
+ * @param {string} extensionPath - a path to the extension's resources.
+ */
+
+setup({ explicit_done: true })
+
+  globalThis.runTestsWithWebExtension = function(extensionPath) {
+    test_driver.install_web_extension({
+        type: "path",
+        path: extensionPath
+    })
+    .then((result) => {
+      let test;
+
+      browser.test.onTestStarted.addListener((message, data) => {
+        test = async_test(data.testName)
+      })
+
+      browser.test.onTestStarted.addListener((message, data) => {
+      })
+
+      browser.test.onTestFinished.addListener((message, data) => {
+        test.step(() => {
+          let description = data.message ? `${data.assertionDescription}. ${data.message}` : data.assertionDescription
+          assert_true(data.result, description)
+        })
+      test.done()
+
+      if (!data.result)
+        test.set_status(test.FAIL)
+
+      if (!data.remainingTests)
+          test_driver.uninstall_web_extension(result.extension).then(() => { done() })
+      })
+    })
+  }

tools/lint/lint.py

@@ -599,7 +599,7 @@ def is_query_string_correct(script: Text, src: Text,
         if not is_path_correct("testdriver.js", src):
             errors.append(rules.TestdriverPath.error(path))
         if not is_query_string_correct("testdriver.js", src,
-                                       {'feature': ['bidi']}):
+                                       {'feature': ['bidi', 'extensions']}):
             errors.append(rules.TestdriverUnsupportedQueryParameter.error(path))
 
         if (not is_path_correct("testdriver-vendor.js", src) or

tools/manifest/sourcefile.py

@@ -379,6 +379,12 @@ def name_is_window(self) -> bool:
         be a window js test file"""
         return "window" in self.meta_flags and self.ext == ".js"
 
+    @property
+    def name_is_extension(self) -> bool:
+        """Check if the file name matches the conditions for the file to
+        be a extension js test file"""
+        return "extension" in self.meta_flags and self.ext == ".js"
+
     @property
     def name_is_webdriver(self) -> bool:
         """Check if the file name matches the conditions for the file to
@@ -467,7 +473,7 @@ def pac_nodes(self) -> List[ElementTree.Element]:
 
     @cached_property
     def script_metadata(self) -> Optional[List[Tuple[Text, Text]]]:
-        if self.name_is_worker or self.name_is_multi_global or self.name_is_window:
+        if self.name_is_worker or self.name_is_multi_global or self.name_is_window or self.name_is_extension:
             regexp = js_meta_re
         elif self.name_is_webdriver:
             regexp = python_meta_re
@@ -912,6 +918,9 @@ def possible_types(self) -> Set[Text]:
         if self.name_is_window:
             return {TestharnessTest.item_type}
 
+        if self.name_is_extension:
+            return {TestharnessTest.item_type}
+
         if self.markup_type is None:
             return {SupportFile.item_type}
 
@@ -1076,6 +1085,22 @@ def manifest_items(self) -> Tuple[Text, List[ManifestItem]]:
             ]
             rv = TestharnessTest.item_type, tests
 
+        elif self.name_is_extension:
+            test_url = replace_end(self.rel_url, ".extension.js", ".extension.html")
+            tests = [
+                TestharnessTest(
+                    self.tests_root,
+                    self.rel_path,
+                    self.url_base,
+                    test_url + variant,
+                    timeout=self.timeout,
+                    pac=self.pac,
+                    script_metadata=self.script_metadata
+                )
+                for variant in self.test_variants
+            ]
+            rv = TestharnessTest.item_type, tests
+
         elif self.content_is_css_manual and not self.name_is_reference:
             rv = ManualTest.item_type, [
                 ManualTest(

tools/serve/serve.py

@@ -314,6 +314,21 @@ class WindowHandler(HtmlWrapperHandler):
 <script src="%(path)s"></script>
 """
 
+class ExtensionHandler(HtmlWrapperHandler):
+    path_replace = [(".extension.html", ".extension.js")]
+    wrapper = """<!doctype html>
+<meta charset=utf-8>
+%(meta)s
+<script src="/resources/testharness.js"></script>
+<script src="/resources/testharnessreport.js"></script>
+<script src="/resources/testdriver.js?feature=extensions"></script>
+<script src="/resources/testdriver-vendor.js"></script>
+<script src="/resources/web-extensions-helper.js"></script>
+%(script)s
+<div id=log></div>
+<script src="%(path)s"></script>
+"""
+
 
 class WindowModulesHandler(HtmlWrapperHandler):
     global_type = "window-module"
@@ -775,6 +790,7 @@ def add_mount_point(self, url_base, path):
             ("GET", "*.worker.html", WorkersHandler),
             ("GET", "*.worker-module.html", WorkerModulesHandler),
             ("GET", "*.window.html", WindowHandler),
+            ("GET", "*.extension.html", ExtensionHandler),
             ("GET", "*.any.html", AnyHtmlHandler),
             ("GET", "*.any.sharedworker.html", SharedWorkersHandler),
             ("GET", "*.any.sharedworker-module.html", SharedWorkerModulesHandler),

tools/webdriver/webdriver/client.py

@@ -763,6 +763,14 @@ def print(self,
                 body[prop] = value
         return self.send_session_command("POST", "print", body)
 
+    @command
+    def install_web_extension(self, extension):
+        return self.send_session_command("POST", "webextension", extension)
+
+    @command
+    def uninstall_web_extension(self, extension_id):
+        return self.send_session_command("DELETE", "webextension/%s" % extension_id)
+
 
 class ShadowRoot:
     identifier = "shadow-6066-11e4-a52e-4f735466cecf"

tools/wptrunner/wptrunner/browsers/chrome.py

@@ -278,7 +278,7 @@ def require_webdriver_bidi(self) -> Optional[bool]:
     def settings(self, test: Test) -> BrowserSettings:
         """ Required to store `require_webdriver_bidi` in browser settings."""
         settings = super().settings(test)
-        self._require_webdriver_bidi = test.testdriver_features is not None and 'bidi' in test.testdriver_features
+        self._require_webdriver_bidi = (test.testdriver_features is not None and ('bidi' in test.testdriver_features or 'extensions' in test.testdriver_features))
 
         return {
             **settings,

tools/wptrunner/wptrunner/executors/actions.py

@@ -523,6 +523,28 @@ def __call__(self, payload):
         owner, name, hashes = payload["owner"], payload["name"], payload["hashes"]
         return self.protocol.protected_audience.set_k_anonymity(owner, name, hashes)
 
+class InstallWebExtensionAction:
+    name = "install_web_extension"
+
+    def __init__(self, logger, protocol):
+        self.logger = logger
+        self.protocol = protocol
+
+    def __call__(self, payload):
+        self.logger.debug("installing web extension")
+        return self.protocol.web_extensions.install_web_extension(payload["extension"])
+
+class UninstallWebExtensionAction:
+    name = "uninstall_web_extension"
+
+    def __init__(self, logger, protocol):
+        self.logger = logger
+        self.protocol = protocol
+
+    def __call__(self, payload):
+        self.logger.debug("uninstalling web extension")
+        return self.protocol.web_extensions.uninstall_web_extension(payload["extension_id"])
+
 actions = [ClickAction,
            DeleteAllCookiesAction,
            GetAllCookiesAction,
@@ -563,4 +585,6 @@ def __call__(self, payload):
            CreateVirtualPressureSourceAction,
            UpdateVirtualPressureSourceAction,
            RemoveVirtualPressureSourceAction,
-           SetProtectedAudienceKAnonymityAction]
+           SetProtectedAudienceKAnonymityAction,
+           InstallWebExtensionAction,
+           UninstallWebExtensionAction]

tools/wptrunner/wptrunner/executors/asyncactions.py

@@ -128,10 +128,35 @@ async def __call__(self, payload):
                                                                    state,
                                                                    origin)
 
+class BidiInstallWebExtensionAction:
+    name = "bidi.web_extensions.install_web_extension"
+
+    def __init__(self, logger, protocol):
+        do_delayed_imports()
+        self.logger = logger
+        self.protocol = protocol
+
+    def __call__(self, payload):
+        return self.protocol.bidi_web_extensions.install_web_extension(payload['extension'])
+
+
+class BidiUninstallWebExtensionAction:
+    name = "bidi.web_extensions.uninstall_web_extension"
+
+    def __init__(self, logger, protocol):
+        do_delayed_imports()
+        self.logger = logger
+        self.protocol = protocol
+
+    def __call__(self, payload):
+        return self.protocol.bidi_web_extensions.uninstall_web_extension(payload['extension'])
+
 
 async_actions = [
     BidiBluetoothHandleRequestDevicePrompt,
     BidiBluetoothSimulateAdapterAction,
     BidiBluetoothSimulatePreconnectedPeripheralAction,
+    BidiInstallWebExtensionAction,
     BidiPermissionsSetPermissionAction,
-    BidiSessionSubscribeAction]
+    BidiSessionSubscribeAction,
+    BidiUninstallWebExtensionAction]