feat: Make the plugin compatible with Appium 3 (#35)

BREAKING CHANGE: The minimum required Appium server version is set to 3.0.0

Author: mykola-mokhnach

.eslintignore

@@ -22,19 +22,22 @@ jobs:
       APPIUM_TEST_SERVER_PORT: 4567
       APPIUM_TEST_SERVER_HOST: 127.0.0.1
       _FORCE_LOGS: 1
-    # No hardware acceleration is available for emulators on Ubuntu:
-    # https://github.com/marketplace/actions/android-emulator-runner#can-i-use-this-action-on-linux-vms
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-node@v3
       with:
         node-version: lts/*
         check-latest: true
     - uses: actions/setup-java@v3
       with:
         distribution: 'temurin'
-        java-version: '11'
+        java-version: '17'
+    - name: Enable KVM group perms
+      run: |
+        echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
+        sudo udevadm control --reload-rules
+        sudo udevadm trigger --name-match=kvm
     - run: npm install
       name: Install dev dependencies
     - run: |
@@ -64,6 +67,7 @@ jobs:
         sdcard-path-or-size: 1500M
         api-level: ${{ matrix.apiLevel }}
         disable-spellchecker: true
+        emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim
         target: ${{ matrix.emuTag }}
         arch: ${{ matrix.arch }}
         ram-size: 4096M

.eslintrc.json

@@ -1,15 +1,16 @@
 name: Conventional Commits
 on:
   pull_request:
+    types: [opened, edited, synchronize, reopened]
 
 
 jobs:
   lint:
     name: https://www.conventionalcommits.org
     runs-on: ubuntu-latest
     steps:
-      - uses: beemojs/conventional-pr-action@v2
-        with:
-          config-preset: angular
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    - uses: beemojs/conventional-pr-action@v3
+      with:
+        config-preset: angular
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/functional-test.yml

@@ -7,12 +7,11 @@ jobs:
   prepare_matrix:
     runs-on: ubuntu-latest
     outputs:
-      versions: ${{ steps.generate-matrix.outputs.versions }}
+      versions: ${{ steps.generate-matrix.outputs.lts }}
     steps:
-    - name: Select 3 most recent LTS versions of Node.js
+    - name: Select all current LTS versions of Node.js
       id: generate-matrix
-      run: echo "versions=$(curl -s https://endoflife.date/api/nodejs.json | jq -c '[[.[] | select(.lts != false)][:3] | .[].cycle | tonumber]')" >> "$GITHUB_OUTPUT"
-
+      uses: msimerson/node-lts-versions@v1
 
   test:
     needs:

.github/workflows/pr-title.yml

@@ -4,6 +4,9 @@ This plugin is created to expose [Chrome Devtools Protocol](https://chromedevtoo
 Afterwards this API could be used to establish a connection to it from an external client and to
 perform an extended automation, like [performance metrics gathering](https://www.selenium.dev/documentation/webdriver/bidirectional/chrome_devtools/#collect-performance-metrics) or [geolocation emulation](https://www.selenium.dev/documentation/webdriver/bidirectional/chrome_devtools/#emulate-geo-location-with-the-remote-webdriver).
 
+> [!IMPORTANT]
+> Since major version *1.0.0*, this plugin is only compatible with Appium 3.
+
 ## Features
 
 * Adds the following execute methods:
@@ -26,7 +29,7 @@ perform an extended automation, like [performance metrics gathering](https://www
 
 ## Prerequisites
 
-* Appium Server 2.0+
+* Appium Server 3.0+
 * [UIAutomator2](https://github.com/appium/appium-uiautomator2-driver) or [Espresso](https://github.com/appium/appium-espresso-driver) driver
 
 ## Installation - Server

.github/workflows/unit-test.yml

@@ -0,0 +1,10 @@
+import appiumConfig from '@appium/eslint-config-appium-ts';
+
+export default [
+  ...appiumConfig,
+  {
+    ignores: [
+      'docs/**',
+    ],
+  },
+];

README.md

@@ -1,4 +1,4 @@
-import DevtoolsPlugin from './lib/plugin';
+import { DevtoolsPlugin } from './lib/plugin';
 
 export default DevtoolsPlugin;
 export { DevtoolsPlugin };

eslint.config.mjs

@@ -55,7 +55,7 @@ function requireDriverProperties(driver) {
  */
 async function getCandidateSocketNames() {
   const {adb} = requireDriverProperties(this.driver);
-  this.logger.debug('Getting a list of candidate devtools sockets');
+  this.log.debug('Getting a list of candidate devtools sockets');
   const out = await adb.shell(['cat', '/proc/net/unix']);
   const names = [];
   const allMatches = [];
@@ -78,12 +78,12 @@ async function getCandidateSocketNames() {
     names.push(sockPath);
   }
   if (_.isEmpty(names)) {
-    this.logger.debug('Found no active devtools sockets');
+    this.log.debug('Found no active devtools sockets');
     if (!_.isEmpty(allMatches)) {
-      this.logger.debug(`Other sockets are: ${JSON.stringify(allMatches, null, 2)}`);
+      this.log.debug(`Other sockets are: ${JSON.stringify(allMatches, null, 2)}`);
     }
   } else {
-    this.logger.debug(
+    this.log.debug(
       `Parsed ${names.length} active devtools ${util.pluralize('socket', names.length, false)}: ` +
         JSON.stringify(names)
     );
@@ -109,9 +109,9 @@ async function getCandidateSocketNames() {
  * @returns {Promise<WebviewProps>}
  */
 async function collectSingleDetails(socketName, localPort) {
-  this.logger.debug(`Collecting CDP data of '${socketName}'`);
+  this.log.debug(`Collecting CDP data of '${socketName}'`);
   const [info, pages] = await B.all([cdpInfo(localPort), cdpList(localPort)]);
-  this.logger.info(`Collected CDP details of '${socketName}'`);
+  this.log.info(`Collected CDP details of '${socketName}'`);
   return {info, pages};
 }
 
@@ -133,12 +133,12 @@ async function collectMultipleDetails(socketNames) {
   /** @type {Record<string, WebviewProps>} */
   const details = {};
   // Connect to each devtools socket and retrieve web view details
-  this.logger.debug(`Collecting CDP data of ${util.pluralize('candidate webview', socketNames.length, true)}`);
+  this.log.debug(`Collecting CDP data of ${util.pluralize('candidate webview', socketNames.length, true)}`);
   const [startPort, endPort] = DEVTOOLS_LOOKUP_PORTS_RANGE;
   let localPort;
   try {
     localPort = await findAPortNotInUse(startPort, endPort);
-  } catch (e) {
+  } catch {
     throw new Error(
       `Cannot find any free port to forward candidate Devtools sockets ` +
       `in range ${startPort}..${endPort}`
@@ -149,7 +149,7 @@ async function collectMultipleDetails(socketNames) {
     try {
       await adb.forwardAbstractPort(localPort, remotePort);
     } catch (e) {
-      this.logger.debug(
+      this.log.debug(
         `Could not create a port forward to fetch the details of '${socketName}' socket: ${e.message}`
       );
       continue;
@@ -158,16 +158,16 @@ async function collectMultipleDetails(socketNames) {
     try {
       details[socketName] = await collectSingleDetails.bind(this)(socketName, localPort);
     } catch (e) {
-      this.logger.debug(`Could not fetch the CDP details of '${socketName}' socket: ${e.message}`);
+      this.log.debug(`Could not fetch the CDP details of '${socketName}' socket: ${e.message}`);
     } finally {
       try {
         await adb.removePortForward(localPort);
       } catch (e) {
-        this.logger.debug(e.message);
+        this.log.debug(e.message);
       }
     }
   }
-  this.logger.info(`Collected CDP details of ${util.pluralize('webview', _.size(details), true)}`);
+  this.log.info(`Collected CDP details of ${util.pluralize('webview', _.size(details), true)}`);
   return details;
 }
 
@@ -265,9 +265,9 @@ function prepareWebSocketForwarder (forwardToUrlPattern, entityIdPlaceholder) {
     /** @type {WebSocket} */ wsUpstream,
     /** @type {import('http').IncomingMessage} */ req
   ) => {
-    this.logger.debug(`Got a new websocket connection at ${req.url}`);
+    this.log.debug(`Got a new websocket connection at ${req.url}`);
     if (!req.url) {
-      this.logger.debug('The url is empty. Will ignore');
+      this.log.debug('The url is empty. Will ignore');
       wsUpstream.close(WS_SERVER_POLICY_VIOLATION);
       return;
     }
@@ -276,7 +276,7 @@ function prepareWebSocketForwarder (forwardToUrlPattern, entityIdPlaceholder) {
     const dstUrl = entityId && forwardToUrlPattern.includes(entityIdPlaceholder)
       ? forwardToUrlPattern.replace(entityIdPlaceholder, entityId)
       : forwardToUrlPattern;
-    this.logger.debug(`Will forward upstream ${req.url} to downstream ${dstUrl}`);
+    this.log.debug(`Will forward upstream ${req.url} to downstream ${dstUrl}`);
     const wsDownstream = new WebSocket(dstUrl);
     wsDownstream.on('message', (msg, binary) => {
       if (wsUpstream.readyState === WebSocket.OPEN) {
@@ -289,13 +289,13 @@ function prepareWebSocketForwarder (forwardToUrlPattern, entityIdPlaceholder) {
       }
     });
     wsDownstream.once('error', (e) => {
-      this.logger.warn(`Got an error from the downstream ${dstUrl}: ${e.message}`);
+      this.log.warn(`Got an error from the downstream ${dstUrl}: ${e.message}`);
     });
     wsUpstream.once('error', (e) => {
-      this.logger.info(`Got an error from the upstream ${req.url}: ${e.message}`);
+      this.log.info(`Got an error from the upstream ${req.url}: ${e.message}`);
     });
     wsDownstream.once('close', (code, reason) => {
-      this.logger.info(
+      this.log.info(
         `The downstream ${dstUrl} has been closed: ${code}, ` +
         `${reason || '(no reason given)'}`
       );
@@ -304,7 +304,7 @@ function prepareWebSocketForwarder (forwardToUrlPattern, entityIdPlaceholder) {
       }
     });
     wsUpstream.once('close', (code, reason) => {
-      this.logger.info(
+      this.log.info(
         `The upstream ${req.url} has been closed: ${code}, ` +
         `${reason || '(no reason given)'}`
       );
@@ -332,7 +332,7 @@ export async function proxyDevtoolsTarget (next, driver, name, port) {
     throw new Error(`The target '${name}' is already being proxied`);
   }
 
-  this.logger.debug(`Starting the proxy for the Devtools target '${name}'`);
+  this.log.debug(`Starting the proxy for the Devtools target '${name}'`);
   let localPort = port;
   if (localPort) {
     if (await checkPortStatus(localPort) !== 'closed') {
@@ -345,7 +345,7 @@ export async function proxyDevtoolsTarget (next, driver, name, port) {
     const [startPort, endPort] = DEVTOOLS_BIND_PORTS_RANGE;
     try {
       localPort = await findAPortNotInUse(startPort, endPort);
-    } catch (e) {
+    } catch {
       throw new Error(
         `Cannot find any free port in range ${startPort}..${endPort} ` +
         `to forward the Devtools socket '${name}'. Try to provide a custom port ` +
@@ -358,7 +358,7 @@ export async function proxyDevtoolsTarget (next, driver, name, port) {
     try {
       await adb.removePortForward(localPort);
     } catch (e) {
-      this.logger.debug(`Cannot remove the port forward. Original error: ${e.message}`);
+      this.log.debug(`Cannot remove the port forward. Original error: ${e.message}`);
     }
   };
   try {
@@ -378,7 +378,7 @@ export async function proxyDevtoolsTarget (next, driver, name, port) {
   }
   const browserDebuggerUrl = details.info[DEBUGGER_URL_KEY];
   if (!browserDebuggerUrl) {
-    this.logger.debug(JSON.stringify(details.info));
+    this.log.debug(JSON.stringify(details.info));
     await removePortForward();
     throw new Error(
       `The target '${name}' cannot be proxied. ` +
@@ -400,7 +400,7 @@ export async function proxyDevtoolsTarget (next, driver, name, port) {
   let wdUrl;
   try {
     wdUrl = new URL(browserDebuggerUrl);
-  } catch (e) {
+  } catch {
     await removePortForward();
     throw new Error(
       `The target '${name}' cannot be proxied. ` +
@@ -453,7 +453,7 @@ export async function proxyDevtoolsTarget (next, driver, name, port) {
     port: localPort,
     rewrites,
   };
-  this.logger.info(
+  this.log.info(
     `Successfully started the proxy for the Devtools target '${name}' at ${forwardTo}: ` +
     JSON.stringify(this.proxiedSessions[alias], null, 2)
   );
@@ -474,7 +474,7 @@ export async function unproxyDevtoolsTarget (next, driver, name) {
     throw new Error(`The target '${name}' is not being proxied`);
   }
 
-  this.logger.debug(`Stopping the proxy for the Devtools target '${name}'`);
+  this.log.debug(`Stopping the proxy for the Devtools target '${name}'`);
   const {
     browserDebuggerPathname,
     pageDebuggerPathname,
@@ -489,10 +489,10 @@ export async function unproxyDevtoolsTarget (next, driver, name) {
     try {
       await step();
     } catch (e) {
-      this.logger.warn(e.message);
+      this.log.warn(e.message);
     }
   }
-  this.logger.info(
+  this.log.info(
     `Successfully stopped the proxy for the Devtools target '${name}': ` +
     JSON.stringify(this.proxiedSessions[alias], null, 2)
   );

index.js

@@ -69,7 +69,6 @@ export default class DevtoolsPlugin extends BasePlugin {
   });
 
   /** @type {import('@appium/types').UpdateServerCallback} */
-  // eslint-disable-next-line require-await
   static async updateServer(expressApp) {
     const buildHanlder = (
       /** @type {string} */methodName,
@@ -79,11 +78,12 @@ export default class DevtoolsPlugin extends BasePlugin {
     ) => {
       const plugin = findPlugin(req.params.uuid);
       if (!plugin) {
-        logger.debug(`Cannot find any plugin instance identified by ${req.params.uuid}. Is is still alive?`);
+        logger.debug(`Cannot find any plugin instance identified by ${req.params.uuid}. Is it still alive?`);
         res.status(404).send();
         return;
       }
       try {
+        // eslint-disable-next-line import/namespace
         const result = await cmdMethods[methodName].bind(plugin)(req);
         res.status(200).json(result);
       } catch (e) {
@@ -123,9 +123,8 @@ export default class DevtoolsPlugin extends BasePlugin {
    */
   async handle(next, driver, cmdName, ...cmdArgs) {
     if (!this.driverRef && 'adb' in driver && driver.adb) {
-      // eslint-disable-next-line no-undef
       this.driverRef = new WeakRef(driver);
-      this.logger.info(`Successfully initialized with ${driver.constructor.name}`);
+      this.log.info(`Successfully initialized with ${driver.constructor.name}`);
     }
 
     switch (cmdName) {