feat: enable appium-inspector as an appium plugin

app/web/polyfills.js

@@ -2,10 +2,14 @@ import i18NextBackend from 'i18next-chained-backend';
 import HttpApi from 'i18next-http-backend';
 import LocalStorageBackend from 'i18next-localstorage-backend';
 
+// Adjust locales path depending on Vite base (web vs plugin)
+const viteBase = import.meta.env.BASE_URL;
+const vitePath = viteBase.endsWith('/') ? viteBase : `${viteBase}/`;
+
 const localesPath =
   process.env.NODE_ENV === 'development'
     ? '/locales' // 'public' folder contents are served at '/'
-    : '../locales'; // from 'dist-browser/assets/'
+    : `..${vitePath}locales`; // from 'dist-browser/assets/'
 
 const i18NextBackendOptions = {
   backends: [LocalStorageBackend, HttpApi],

package.json

@@ -34,16 +34,19 @@
     "build": "npm run build:browser && npm run build:electron",
     "build:browser": "vite build",
     "build:browser:url": "vite build --base $PUBLIC_URL",
+    "build:plugin": "vite build --base /inspector --outDir ../../plugins/dist-browser",
     "build:electron": "electron-vite build",
     "preview:browser": "npm run build:browser && vite preview",
     "preview:electron": "electron-vite preview",
     "pack:electron": "electron-builder build --publish never",
     "clean": "npm run clean:electron && npm run clean:browser && npm run clean:npm",
     "clean:electron": "rimraf dist/ && rimraf node_modules/.vite/ && rimraf node_modules/.vite-electron-renderer/",
     "clean:browser": "rimraf dist-browser/ && rimraf node_modules/.vite/",
+    "clean:plugin": "rimraf plugins/dist-browser",
     "clean:npm": "rimraf package-lock.json && rimraf node_modules && npm install",
     "build:docs": "appium-docs build",
     "dev:docs": "appium-docs build --serve",
+    "plugin:sync:version": "node ./scripts/sync-plugin.mjs",
     "publish:docs": "appium-docs build --deploy --push -b docs-site -m 'docs: build docs for appium-inspector@%s' --alias latest",
     "install-docs-deps": "appium-docs init --no-mkdocs",
     "postversion": "git pull --tags && git push && git push --tags",

plugins/README.md

@@ -0,0 +1,54 @@
+# Appium Inspector Plugin
+
+A plugin that integrates the [Appium Inspector](https://github.com/appium/appium-inspector) directly into your Appium server installation, providing a web-based interface for inspecting and interacting with your application under test.
+
+## Features
+
+- Web-based Appium Inspector interface accessible via `/inspector` endpoint with appium server
+- Full feature parity with standalone Appium Inspector
+
+## Installation
+
+Install the plugin using one of the following methods:
+
+```bash
+# Install from local directory. Then, please run 'npm run build:plugin' as well.
+appium plugin install --source=local /path/to/appium-inspector/plugins
+```
+
+> [!Note]
+> Appium 3 will support this plugin as a first-class plugin with `appium plugin install inspector`
+
+## Usage
+
+1. Start Appium server with the inspector plugin enabled:
+
+```bash
+appium --use-plugins=inspector --allow-cors
+```
+
+2. Access the Inspector interface by navigating to:
+
+```
+http://localhost:4723/inspector
+```
+
+## Development
+
+1. `git clone` this repositiry
+2. `appium plugin install --source=local /path/to/appium-inspector/plugins`
+3. Update the plugin content with `npm run build:plugin` in `/path/to/appium-inspector`
+4. Start Appium with `appium --use-plugins=inspector --allow-cors`
+
+This plugin only needs the `appium` server as a `peerDependencies`.
+
+## Release
+
+(TODO: add this release steps in .github/workflows/package.yml later as another PR)
+
+1. Run `npm run plugin:sync:version` to sync the version with the root project.json
+2. Run `npm publish` in `/path/to/appium-inspector/plugins` to publish the module
+
+## License
+
+[Apache-2.0](https://github.com/appium/appium-inspector/blob/main/LICENSE)

plugins/index.mjs

@@ -0,0 +1,44 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {BasePlugin} from 'appium/plugin.js';
+const PLUGIN_ROOT_PATH = '/inspector';
+const INDEX_HTML = 'index.html';
+const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), 'dist-browser');
+
+/**
+ * Appium Inspector Plugin class
+ * @extends {BasePlugin}
+ */
+export class AppiumInspectorPlugin extends BasePlugin {
+  /**
+   * Creates an instance of AppiumInspectorPlugin
+   * @param {string} name - The name of the plugin
+   * @param {Record<string, unknown>} cliArgs - Command line arguments
+   */
+  constructor(name, cliArgs) {
+    super(name, cliArgs);
+  }
+
+  /**
+   * Handles inspector page requests
+   * @param {import('express').Request} req - Express request object
+   * @param {import('express').Response} res - Express response object
+   * @returns {Promise<void>}
+   */
+  static async openInspector(req, res) {
+    const reqPath =
+      req.path === PLUGIN_ROOT_PATH ? INDEX_HTML : req.path.substring(PLUGIN_ROOT_PATH.length);
+    res.sendFile(reqPath, {root: ROOT_DIR});
+  }
+
+  /**
+   * Updates the Express server configuration
+   * @param {import('express').Application} expressApp - Express application instance
+   * @returns {Promise<void>}
+   */
+  static async updateServer(expressApp) {
+    // Handle both /inspector and /inspector/* paths
+    expressApp.all(['/inspector', '/inspector/*'], AppiumInspectorPlugin.openInspector);
+  }
+}

plugins/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "appium-inspector-plugin",
+  "version": "2024.12.1",
+  "description": "An app inspector for use with an Appium server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appium/appium-inspector.git"
+  },
+  "author": {
+    "name": "Appium Developers",
+    "url": "https://github.com/appium"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/appium/appium-inspector/issues"
+  },
+  "keywords": [
+    "appium"
+  ],
+  "homepage": "https://github.com/appium/appium-inspector",
+  "main": "index.mjs",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "appium": "^2.0.0"
+  },
+  "files": [
+    "index.mjs",
+    "package.json",
+    "dist-browser",
+    "README.md"
+  ],
+  "dependencies": {},
+  "devDependencies": {},
+  "engines": {
+    "node": ">=20.x",
+    "npm": ">=10.x"
+  },
+  "appium": {
+    "pluginName": "inspector",
+    "mainClass": "AppiumInspectorPlugin"
+  }
+}

scripts/sync-plugin.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const PROJECT_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const ROOT_PKG_JSON_PATH = path.resolve(PROJECT_ROOT, '..', 'package.json');
+const PLUGIN_PKG_JSON_PATH = path.resolve(PROJECT_ROOT, '..', 'plugins', 'package.json');
+
+const SYNC_PACKAGE_KEYS = [
+  // To update ever version release
+  'version',
+
+  // These basic information should be the same with the top package.json
+  'engines',
+  'license',
+  'repository',
+  'author',
+  'bugs',
+  'homepage',
+];
+
+/**
+ * Return JSON parsed contents from the given path.
+ * @param {string} path
+ * @returns {Promise<object>}
+ */
+async function readJsonContent(jsonPath) {
+  return await JSON.parse(await fs.readFile(jsonPath, 'utf8'));
+}
+
+async function main() {
+  const [rootJsonContent, pluginJsonContent] = await Promise.all(
+    [ROOT_PKG_JSON_PATH, PLUGIN_PKG_JSON_PATH].map(readJsonContent),
+  );
+
+  for (const key in SYNC_PACKAGE_KEYS) {
+    pluginJsonContent[key] = rootJsonContent[key];
+  }
+
+  // The new line in the last is to avoid prettier error.
+  await fs.writeFile(
+    PLUGIN_PKG_JSON_PATH,
+    `${JSON.stringify(pluginJsonContent, null, 2)}\n`,
+    'utf8',
+  );
+}
+
+(async () => await main())();