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,33 @@ 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.addTest(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

@@ -1302,7 +1302,47 @@
          */
         remove_virtual_pressure_source: function(source_type, context=null) {
             return window.test_driver_internal.remove_virtual_pressure_source(source_type, context);
-        }
+        },
+
+        /**
+         * Loads a WebExtension.
+         *
+         * Matches the `Load Web Extension
+         * <https://github.com/w3c/webextensions/blob/main/specification/webdriver-classic.bs>`_
+         * WebDriver command.
+         * In addition to the
+         * `webExtension.Install <https://www.w3.org/TR/webdriver-bidi/#command-webExtension-install> command`_
+         *
+         * @param {String} type - A type such as "path", "archviePath", 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 specs.
+         *                    Rejected if the extension fails to load.
+         */
+        load_web_extension: function(path) {
+            return window.test_driver_internal.load_web_extension(path);
+        },
+
+        /**
+         * Unloads a WebExtension.
+         *
+         * Matches the `Unload Web Extension
+         * <https://github.com/w3c/webextensions/blob/main/specification/webdriver-classic.bs>`_
+         * WebDriver command.
+         * In addition to the
+         * `webExtension.Uninstall <https://www.w3.org/TR/webdriver-bidi/#command-webExtension-uninstall> 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.
+         */
+        unload_web_extension: function(extension) {
+            return window.test_driver_internal.unload_web_extension(extension);
+        },
     };
 
     window.test_driver_internal = {

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
@@ -865,6 +871,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}
 
@@ -1004,6 +1013,7 @@ def manifest_items(self) -> Tuple[Text, List[ManifestItem]]:
                     test_url + variant,
                     timeout=self.timeout,
                     pac=self.pac,
+                    extension=self.extension,
                     script_metadata=self.script_metadata
                 )
                 for variant in self.test_variants
@@ -1026,6 +1036,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,64 @@ 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=bidi"></script>
+<script src="/resources/testdriver-vendor.js"></script>
+%(script)s
+<div id=log></div>
+<script>
+  setup({ explicit_done: true })
+
+  function runTestsWithWebExtension(extensionPath) {
+    test_driver.load_web_extension({
+        type: "path",
+        path: extensionPath
+    })
+    .then((result) => {
+      let test;
+
+      browser.test.onMessage.addListener((message, data) => {
+        switch(message) {
+          case "assert":
+            test.step(() => {
+              assert_true(data.result, data.message)
+            })
+
+            break
+          case "assert-equality":
+            test.step(() => {
+              assert_true(data.result, `Expected: ${data.expectedValue}; Actual: ${data.actualValue}; Description: ${data.message}`)
+            })
+
+            break
+          case "test-started":
+            test = async_test(data.testName)
+
+            break
+          case "test-finished":
+            test.done()
+
+            if (!data.remainingTests)
+                test_driver.unload_web_extension(result.extension)
+                    .then(() => {
+                        done()
+                    })
+
+            break
+        }
+      })
+    })
+  }
+</script>
+<script src="%(path)s"></script>
+"""
+
 
 class WindowModulesHandler(HtmlWrapperHandler):
     global_type = "window-module"
@@ -775,6 +833,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/bidi/modules/web_extensions.py

@@ -0,0 +1,25 @@
+from typing import Any, Mapping
+
+from ._module import BidiModule, command
+
+
+class WebExtension(BidiModule):
+    @command
+    def install(self, params: Mapping[str, str]) -> Mapping[str, Any]:
+        """
+        Represents a command `webExtension.install` specified in
+        https://www.w3.org/TR/webdriver-bidi/#command-webExtension-install
+        """
+
+        return params
+
+    @command
+    def uninstall(self, extension_id) -> Mapping[str, Any]:
+        """
+        Represents a command `webExtension.Uninstall` specified in
+        https://www.w3.org/TR/webdriver-bidi/#command-webExtension-uninstall
+        """
+
+        return {
+            "extension": extension_id
+        }

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 load_web_extension(self, extension):
+        return self.send_session_command("POST", "webextension", extension)
+
+    @command
+    def unload_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/executors/actions.py

@@ -511,6 +511,28 @@ def __call__(self, payload):
         source_type = payload["source_type"]
         return self.protocol.pressure.remove_virtual_pressure_source(source_type)
 
+class LoadWebExtensionAction:
+    name = "load_web_extension"
+
+    def __init__(self, logger, protocol):
+        self.logger = logger
+        self.protocol = protocol
+
+    def __call__(self, payload):
+        self.logger.debug("loading web extension")
+        return self.protocol.web_extensions.load_web_extension(payload["extension"])
+
+class UnloadWebExtensionAction:
+    name = "unload_web_extension"
+
+    def __init__(self, logger, protocol):
+        self.logger = logger
+        self.protocol = protocol
+
+    def __call__(self, payload):
+        self.logger.debug("unloading web extension")
+        return self.protocol.web_extensions.unload_web_extension(payload["extension_id"])
+
 actions = [ClickAction,
            DeleteAllCookiesAction,
            GetAllCookiesAction,
@@ -550,4 +572,6 @@ def __call__(self, payload):
            RunBounceTrackingMitigationsAction,
            CreateVirtualPressureSourceAction,
            UpdateVirtualPressureSourceAction,
-           RemoveVirtualPressureSourceAction]
+           RemoveVirtualPressureSourceAction,
+           LoadWebExtensionAction,
+           UnloadWebExtensionAction]

tools/wptrunner/wptrunner/executors/executorwebdriver.py

@@ -45,6 +45,7 @@
                        DevicePostureProtocolPart,
                        StorageProtocolPart,
                        VirtualPressureSourceProtocolPart,
+                       WebExtensionsProtocolPart,
                        merge_dicts)
 
 from typing import List, Optional, Tuple
@@ -251,6 +252,23 @@ async def set_permission(self, descriptor, state, origin):
         return await self.webdriver.bidi_session.permissions.set_permission(
             descriptor=descriptor, state=state, origin=origin)
 
+class WebDriverBidiWebExtensionsProtocolPart(WebExtensionsProtocolPart):
+    def __init__(self, parent):
+        super().__init__(parent)
+        self.webdriver = None
+
+    def setup(self):
+        self.webdriver = self.parent.webdriver
+
+    def load_web_extension(self, extension):
+        if extension["type"] == "path" and self.parent.test_path:
+            extension_path = self.parent.test_path[:self.parent.test_path.rfind('/')]
+            extension["path"] = extension_path + extension.get("path")
+
+        return self.webdriver.loop.run_until_complete(self.webdriver.bidi_session.web_extension.install(extension))
+
+    def unload_web_extension(self, extension_id):
+        return self.webdriver.loop.run_until_complete(self.webdriver.bidi_session.web_extension.uninstall(extension_id))
 
 class WebDriverTestharnessProtocolPart(TestharnessProtocolPart):
     def setup(self):
@@ -669,6 +687,20 @@ def update_virtual_pressure_source(self, source_type, sample):
     def remove_virtual_pressure_source(self, source_type):
         return self.webdriver.send_session_command("DELETE", "pressuresource/%s" % source_type)
 
+class WebDriverWebExtensionsProtocolPart(WebExtensionsProtocolPart):
+    def setup(self):
+        self.webdriver = self.parent.webdriver
+
+    def load_web_extension(self, extension):
+        if extension["type"] == "path" and self.parent.test_path:
+            extension_path = self.parent.test_path[:self.parent.test_path.rfind('/')]
+            extension["path"] = extension_path + extension.get("path")
+
+        return self.webdriver.load_web_extension(extension)
+
+    def unload_web_extension(self, extension_id):
+        return self.webdriver.unload_web_extension(extension_id)
+
 
 class WebDriverProtocol(Protocol):
     enable_bidi = False
@@ -693,7 +725,8 @@ class WebDriverProtocol(Protocol):
                   WebDriverVirtualSensorPart,
                   WebDriverDevicePostureProtocolPart,
                   WebDriverStorageProtocolPart,
-                  WebDriverVirtualPressureSourceProtocolPart]
+                  WebDriverVirtualPressureSourceProtocolPart,
+                  WebDriverWebExtensionsProtocolPart]
 
     def __init__(self, executor, browser, capabilities, **kwargs):
         super().__init__(executor, browser)
@@ -769,6 +802,7 @@ class WebDriverBidiProtocol(WebDriverProtocol):
                   WebDriverBidiEventsProtocolPart,
                   WebDriverBidiPermissionsProtocolPart,
                   WebDriverBidiScriptProtocolPart,
+                  WebDriverBidiWebExtensionsProtocolPart,
                   *(part for part in WebDriverProtocol.implements)
                   ]
 
@@ -975,6 +1009,7 @@ def on_environment_change(self, new_environment):
 
     def do_test(self, test):
         url = self.test_url(test)
+        self.protocol.test_path = test.path
 
         success, data = WebDriverRun(self.logger,
                                      self.do_testharness,