APIs for shimming standard APIs

README.md

@@ -91,6 +91,23 @@ To handle the difference in scope injection we expose multiple utilities which b
         return await nativeImpl.call(this, queryObject)
     })
     ```
+- `ContentFeature.shimInterface(interfaceName, ImplClass, options)`
+    - API for shimming standard constructors. See the WebCompat feature and JSDoc for more details.
+    - Example usage:
+    ```javascript
+    this.shimInterface('MediaSession', MyMediaSessionClass, {
+        disallowConstructor: true,
+        allowConstructorCall: false,
+        wrapToString: true
+    })
+    ```
+- `ContentFeature.shimProperty(instanceHost, instanceProp, implInstance, readOnly = false)`
+    - API for shimming standard global objects. Usually you want to call `shimInterface()` first, and pass an object instance as `implInstance`. See the WebCompat feature and JSDoc for more details.
+    - Example usage:
+    ```javascript
+    this.shimProperty(Navigator.prototype, 'mediaSession', myMediaSessionInstance, true)
+    ```
+
 - `DDGProxy`
     - Behaves a lot like `new window.Proxy` with a few differences:
         - has an `overload` method to actually apply the function to the native property.

integration-test/test-pages.js

@@ -21,7 +21,57 @@ describe('Test integration pages', () => {
         await teardown()
     })
 
-    it('Should be successful page script check', async () => {
+    /**
+     * @param {string} pageName
+     * @param {string} configPath
+     * @param {string} [evalBeforeInit]
+     */
+    async function testPage (pageName, configPath, evalBeforeInit) {
+        const port = server.address().port
+        const page = await browser.newPage()
+        const res = fs.readFileSync(configPath)
+        // @ts-expect-error - JSON.parse returns any
+        const config = JSON.parse(res)
+        polyfillProcessGlobals()
+
+        /** @type {import('../src/utils.js').UserPreferences} */
+        const userPreferences = {
+            platform: {
+                name: 'extension'
+            },
+            sessionKey: 'test'
+        }
+        const processedConfig = processConfig(config, /* userList */ [], /* preferences */ userPreferences/*, platformSpecificFeatures = [] */)
+
+        await gotoAndWait(page, `http://localhost:${port}/${pageName}?automation=true`, processedConfig, evalBeforeInit)
+        // Check page results
+        const pageResults = await page.evaluate(
+            () => {
+                let res
+                const promise = new Promise(resolve => {
+                    res = resolve
+                })
+                // @ts-expect-error - results is not defined in the type definition
+                if (window.results) {
+                    // @ts-expect-error - results is not defined in the type definition
+                    res(window.results)
+                } else {
+                    window.addEventListener('results-ready', (e) => {
+                        // @ts-expect-error - e.detail is not defined in the type definition
+                        res(e.detail)
+                    })
+                }
+                return promise
+            }
+        )
+        for (const key in pageResults) {
+            for (const result of pageResults[key]) {
+                expect(result.result).withContext(key + ':\n ' + result.name).toEqual(result.expected)
+            }
+        }
+    }
+
+    describe('Runtime checks', () => {
         const pages = {
             'runtime-checks/pages/basic-run.html': 'runtime-checks/config/basic-run.json',
             'runtime-checks/pages/replace-element.html': 'runtime-checks/config/replace-element.json',
@@ -32,49 +82,16 @@ describe('Test integration pages', () => {
         }
         for (const pageName in pages) {
             const configName = pages[pageName]
-
-            const port = server.address().port
-            const page = await browser.newPage()
-            const res = fs.readFileSync(process.cwd() + '/integration-test/test-pages/' + configName)
-            // @ts-expect-error - JSON.parse returns any
-            const config = JSON.parse(res)
-            polyfillProcessGlobals()
-
-            /** @type {import('../src/utils.js').UserPreferences} */
-            const userPreferences = {
-                platform: {
-                    name: 'extension'
-                },
-                sessionKey: 'test'
-            }
-            const processedConfig = processConfig(config, /* userList */ [], /* preferences */ userPreferences/*, platformSpecificFeatures = [] */)
-
-            await gotoAndWait(page, `http://localhost:${port}/${pageName}?automation=true`, processedConfig)
-            // Check page results
-            const pageResults = await page.evaluate(
-                () => {
-                    let res
-                    const promise = new Promise(resolve => {
-                        res = resolve
-                    })
-                    // @ts-expect-error - results is not defined in the type definition
-                    if (window.results) {
-                        // @ts-expect-error - results is not defined in the type definition
-                        res(window.results)
-                    } else {
-                        window.addEventListener('results-ready', (e) => {
-                            // @ts-expect-error - e.detail is not defined in the type definition
-                            res(e.detail)
-                        })
-                    }
-                    return promise
-                }
-            )
-            for (const key in pageResults) {
-                for (const result of pageResults[key]) {
-                    expect(result.result).withContext(key + ':\n ' + result.name).toEqual(result.expected)
-                }
-            }
+            it(`${pageName}`, async () => {
+                await testPage(pageName, process.cwd() + '/integration-test/test-pages/' + configName)
+            })
         }
     })
+
+    it('Web compat shims correctness', async () => {
+        await testPage(
+            'webcompat/pages/shims.html',
+            `${process.cwd()}/integration-test/test-pages/webcompat/config/shims.json`
+        )
+    })
 })

integration-test/test-pages/webcompat/config/shims.json

@@ -0,0 +1,11 @@
+{
+    "features": {
+        "webCompat": {
+            "state": "enabled",
+            "settings": {
+                "mediaSession": "enabled",
+                "presentation": "enabled"
+            }
+        }
+    }
+}

integration-test/test-pages/webcompat/pages/shims.html

@@ -0,0 +1,129 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width">
+  <title>Webcompat shims</title>
+  <link rel="stylesheet" href="../../shared/style.css">
+</head>
+<body>
+    <script src="../../shared/utils.js"></script>
+    <p><a href="../index.html">[Webcompat shims]</a></p>
+
+    <p>This page verifies that shims created with shim APIs have correct descriptors</p>
+
+    <script>
+        /**
+         * assert that two descriptors are similar, allowing different values
+         * @param {import('../src/wrapper-utils').StrictPropertyDescriptor} origDesc
+         * @param {import('../src/wrapper-utils').StrictPropertyDescriptor} newDesc
+         * @returns {string} - the error message if the test fails
+         */
+        function compareDescriptorShape (origDesc, newDesc) {
+            const origKeys = Object.keys(origDesc)
+            const newKeys = Object.keys(newDesc)
+            // verify that both descriptors have the same keys
+            if (origKeys.sort().join(',') !== newKeys.sort().join(','))
+                return 'property keys do not match';
+
+            for (const key of origKeys) {
+                if (key === 'get' || key === 'set' || key === 'value') {
+                    if (typeof newDesc[key] !== typeof origDesc[key])
+                        return `property ${key} does not match`;
+                } else {
+                    if (newDesc[key] !== origDesc[key])
+                        return `property ${key} does not match`;
+                }
+            }
+        }
+
+        /**
+         * Use this function to test the interfaces shimmed in the web-compat feature
+         * @param {string} interfaceName - the name of the interface to test. It should be available in the global scope
+         * @param {import('../src/wrapper-utils').StrictPropertyDescriptor} origInterfaceDescriptor - the descriptor of the original interface
+         * @returns {string} - the error message if the test fails
+         */
+        function testInterfaceShimCorrectness (interfaceName, origInterfaceDescriptor) {
+            if (!interfaceName) {
+                return 'Nothing to test.';
+            }
+
+            if (!globalThis[interfaceName])
+                return 'native class is not found after shimming';
+            if (globalThis[interfaceName][globalThis.ddgShimMark] !== true)
+                return 'class should be marked as shimmed';
+
+            const newInterfaceDescriptor = Object.getOwnPropertyDescriptor(globalThis, interfaceName)
+
+            return compareDescriptorShape(origInterfaceDescriptor, newInterfaceDescriptor)
+        }
+
+        /**
+         * Use this function to test the global properties shimmed in the web-compat feature
+         * @param {any} instanceHost - object under which the global instance is defined
+         * @param {string} instanceProp - the name of the instance property
+         * @param {import('../src/wrapper-utils').StrictPropertyDescriptor} origInstanceDescriptor - the descriptor of the original instance property
+         * @returns {string} - the error message if the test fails
+         */
+        function testInstanceShimCorrectness (instanceHost, instanceProp, origInstanceDescriptor) {
+            if (!instanceHost || !instanceProp) {
+                return 'Nothing to test.';
+            }
+
+            if (!instanceHost[instanceProp])
+                return 'global instance is not found after shimming';
+
+            const newInstanceDescriptor = Object.getOwnPropertyDescriptor(instanceHost, instanceProp)
+
+            return compareDescriptorShape(origInstanceDescriptor, newInstanceDescriptor)
+        }
+
+
+        test('Interface shims', async () => {
+            const results = [];
+            results.push({
+                name: 'origInterfaceDescriptors found',
+                result: Boolean(globalThis.origInterfaceDescriptors),
+                expected: true
+            });
+            results.push({
+                name: 'ddgShimMark found',
+                result: Boolean(globalThis.ddgShimMark),
+                expected: true
+            });
+
+            for (const [interfaceName, origDescriptor] of Object.entries(globalThis.origInterfaceDescriptors)) {
+                results.push({
+                    name: `${interfaceName}'s descriptor is correct`,
+                    result: testInterfaceShimCorrectness(interfaceName, origDescriptor),
+                    expected: undefined
+                });
+            }
+
+            return results;
+        });
+
+        test('Instance shims', async () => {
+            const results = [];
+            results.push({
+                name: 'origPropDescriptors found',
+                result: Boolean(globalThis.origPropDescriptors),
+                expected: true
+            });
+
+            for (const [instanceHost, instanceProp, origDescriptor] of globalThis.origPropDescriptors) {
+                results.push({
+                    name: `${instanceHost}.${instanceProp}'s descriptor is correct`,
+                    result: testInstanceShimCorrectness(instanceHost, instanceProp, origDescriptor),
+                    expected: undefined
+                });
+            }
+
+            return results;
+        });
+
+        // eslint-disable-next-line no-undef
+        renderResults();
+    </script>
+</body>
+</html>