appium-remote-debugger 15.6.0 → 15.7.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [15.7.0](https://github.com/appium/appium-remote-debugger/compare/v15.6.0...v15.7.0) (2026-04-17)
+
+### Features
+
+* Add automated atoms compilation script ([#485](https://github.com/appium/appium-remote-debugger/issues/485)) ([aa129f4](https://github.com/appium/appium-remote-debugger/commit/aa129f42beade3f6e1682430d281249eb2f6250d))
+
 ## [15.6.0](https://github.com/appium/appium-remote-debugger/compare/v15.5.0...v15.6.0) (2026-03-10)
 
 ### Features

package/README.md

@@ -21,23 +21,10 @@ The steps to using the `RemoteDebugger` involve instantiating an object, then ru
 
 ## Selenium "atoms"
 
-The remote debugger uses the standard [Selenium Atoms](https://github.com/SeleniumHQ/selenium/tree/master/javascript/atoms)
-to interact with web pages. These need to be manually updated when necessary.
-To do so, simply update the branch in the `scripts/common.mjs`, by modifying the `SELENIUM_BRANCH`
-constant at the top of the file and commit them to explicitly leaves the latest target branch information.
-Then run `npm run build:atoms`, test and create a pull request with the resulting changed atoms directory.
-
-You can set `SELENIUM_GITHUB` and `SELENIUM_BRANCH` environment variables with the npm command to
-customize the target repository and the target branch.
-
-Note that to build the atoms it is required that you have the `bazel` tool installed. Selenium will
-also require that it be installed at a particular version relative to the version of Selenium that
-has been checked out by our build script. It is most convenient simply to install
-[`bazelisk`](https://github.com/bazelbuild/bazelisk) and have it available on your PATH.
-
-One caveat is that there are some changes that are needed for Appium, that are
-not yet in the Selenium codebase. See the [atoms notes](./atoms-notes.md) for
-details.
+The remote debugger uses the standard [Selenium JavaScript atoms](https://github.com/SeleniumHQ/selenium/tree/trunk/javascript/atoms)
+to interact with web pages.
+
+To refresh the bundled `atoms/` output, use the **Update Selenium Atoms** manual workflow ([`.github/workflows/update-atoms.yml`](./.github/workflows/update-atoms.yml)) in the GitHub Actions tab, or build locally. Full steps, inputs, and tooling are documented in **[docs/update-atoms.md](./docs/update-atoms.md)**.
 
 ## Test
 

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "appium"
   ],
-  "version": "15.6.0",
+  "version": "15.7.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {

package/scripts/common.mjs

@@ -1,4 +1,4 @@
-import { fs, logger } from '@appium/support';
+import { fs, logger, util } from '@appium/support';
 import { glob } from 'glob';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -6,12 +6,26 @@ import { exec } from 'teen_process';
 
 const log = logger.getLogger('Atoms');
 
-const SELENIUM_BRANCH = process.env.SELENIUM_BRANCH || 'trunk'; // the hash is '9b1e83ce6409086413b1cd7ffe6da502ac9d11f1'
+const SELENIUM_BRANCH = process.env.SELENIUM_BRANCH || 'trunk';
 const SELENIUM_GITHUB = process.env.SELENIUM_GITHUB || 'https://github.com/SeleniumHQ/selenium.git';
 
+const BAZEL_ATOMS_TARGET = '//javascript/atoms/...';
 const BAZEL_WD_ATOMS_TARGET = '//javascript/webdriver/atoms/...';
 const BAZEL_WD_ATOMS_INJECT_TARGET = '//javascript/webdriver/atoms/inject/...';
-const BAZEL_ATOMS_TARGET = '//javascript/atoms/...';
+
+// `//javascript/atoms/...` includes browser-backed `closure-test*` targets that fetch pinned
+// Firefox/Safari/etc.; exclude them so local/CI atoms import builds without those repositories.
+const BAZEL_ATOMS_EXCLUDED_TARGETS = [
+  '//javascript/atoms:closure-test',
+  '//javascript/atoms:closure-test-all-browsers',
+  '//javascript/atoms:closure-test-chrome',
+  '//javascript/atoms:closure-test-chrome-beta',
+  '//javascript/atoms:closure-test-edge',
+  '//javascript/atoms:closure-test-firefox',
+  '//javascript/atoms:closure-test-firefox-beta',
+  '//javascript/atoms:closure-test-safari',
+  '//javascript/atoms:closure-test_debug_server',
+];
 
 const WORKING_ROOT_DIR = path.resolve(fileURLToPath(import.meta.url), '..', '..');
 const TMP_DIRECTORY = path.resolve(WORKING_ROOT_DIR, 'tmp');
@@ -24,6 +38,17 @@ const BAZEL_WD_ATOMS_DIR = path.join(JS_RELATIVE_DIR, 'webdriver', 'atoms');
 const BAZEL_WD_ATOMS_INJECT_DIR = path.join(BAZEL_WD_ATOMS_DIR, 'inject');
 const ATOMS_DIRECTORY = path.resolve(WORKING_ROOT_DIR, 'atoms');
 const LAST_UPDATE_FILE = path.resolve(ATOMS_DIRECTORY, 'lastupdate');
+let bazelCommand;
+
+function getBazelEnv() {
+  // Selenium atoms build does not require Android SDK. If these env vars are set locally,
+  // Bazel may try to auto-configure Android toolchains and fail on host-specific SDK issues.
+  const env = {...process.env};
+  delete env.ANDROID_HOME;
+  delete env.ANDROID_SDK_ROOT;
+  delete env.ANDROID_SDK;
+  return env;
+}
 
 /**
  * Create a temporary directory to clone selenium repository to build atoms in.
@@ -47,41 +72,74 @@ async function seleniumClean () {
 export async function seleniumClone () {
   await seleniumMkdir();
   await seleniumClean();
-  log.info(`Cloning branch '${SELENIUM_BRANCH}' from '${SELENIUM_GITHUB}'`);
-  await exec('git', [
+  const cloneArgs = (branch) => ([
     'clone',
-    `--branch=${SELENIUM_BRANCH}`,
-    `--depth=1`,
+    `--branch=${branch}`,
+    '--depth=1',
     SELENIUM_GITHUB,
     SELENIUM_DIRECTORY,
   ]);
+
+  log.info(`Cloning branch '${SELENIUM_BRANCH}' from '${SELENIUM_GITHUB}'`);
+  await exec('git', cloneArgs(SELENIUM_BRANCH));
 };
 
 /**
  * Check bazel version if current available bazel version on the host machine
- * is good for the target selenium repository's required version.
+ * meets Selenium's minimum from `.bazelversion` (newer Bazel is allowed).
  */
 async function checkBazel() {
-  log.info('Checking required Bazel version');
-  const bazelVersion = (await fs.readFile(BAZEL_VERSION, 'utf8')).trim();
-  let result;
-  let err;
+  log.info('Checking minimum Bazel version from Selenium .bazelversion');
+  const minBazelVersion = (await fs.readFile(BAZEL_VERSION, 'utf8')).trim();
+  let bazelVersionResult;
+  let bazeliskVersionResult;
+  let bazelVersionErr;
+  let bazeliskVersionErr;
   try {
-    result = await exec('bazel', ['--version']);
+    bazelVersionResult = await exec('bazel', ['--version']);
   } catch (e) {
-    err = e.stderr || e.message;
+    bazelVersionErr = e.stderr || e.message;
+  }
+  if (!bazelVersionErr && !bazelVersionResult.stderr) {
+    // e.g. "bazel 9.0.1"
+    const currentBazelVersion = bazelVersionResult.stdout.trim().split(' ')[1];
+    let meetsMinimum = false;
+    let versionCompareFailed = false;
+    try {
+      meetsMinimum = util.compareVersions(currentBazelVersion, '>=', minBazelVersion);
+    } catch (err) {
+      versionCompareFailed = true;
+      log.warn(
+        `Could not compare Bazel versions (${currentBazelVersion} vs minimum ${minBazelVersion}): ${err.message}. ` +
+        `Trying bazelisk...`
+      );
+    }
+    if (meetsMinimum) {
+      bazelCommand = 'bazel';
+      log.info(`Bazel ${currentBazelVersion} (minimum ${minBazelVersion}) will be used to build atoms.`);
+      return;
+    }
+    if (!versionCompareFailed) {
+      log.warn(
+        `Found bazel ${currentBazelVersion}, but Selenium needs at least ${minBazelVersion}. Trying bazelisk...`
+      );
+    }
   }
-  if (err || result.stderr) {
-    throw new Error(`Please setup Bazel ${bazelVersion} runtime environment by following https://bazel.build/install. ` +
-      `Original error: ${err || result.stderr}`);
+  try {
+    bazeliskVersionResult = await exec('bazelisk', ['--version']);
+  } catch (e) {
+    bazeliskVersionErr = e.stderr || e.message;
   }
-  // e.g. "bazel 7.4.1"
-  const currentBazelVersion = result.stdout.trim().split(' ')[1];
-  if (currentBazelVersion !== bazelVersion) {
-    throw new Error(`Please setup Bazel ${bazelVersion} runtime environment. ` +
-      `Current available version is ${currentBazelVersion}`);
+  if (bazeliskVersionErr || bazeliskVersionResult.stderr) {
+    throw new Error(
+      `Please install Bazel ${minBazelVersion} or newer by following https://bazel.build/install, ` +
+      `or install bazelisk (https://github.com/bazelbuild/bazelisk). ` +
+      `Original errors: bazel='${bazelVersionErr || bazelVersionResult?.stderr || 'unknown'}', ` +
+      `bazelisk='${bazeliskVersionErr || bazeliskVersionResult?.stderr || 'unknown'}'`
+    );
   }
-  log.info(`Bazel ${bazelVersion} will be used to build atoms.`);
+  bazelCommand = 'bazelisk';
+  log.info(`Bazelisk will be used to build atoms (Selenium minimum Bazel ${minBazelVersion}).`);
 }
 
 /**
@@ -97,7 +155,7 @@ async function atomsCleanDir () {
  */
 async function atomsClean () {
   log.info('Building atoms');
-  await exec('bazel', ['clean'], {cwd: SELENIUM_DIRECTORY});
+  await exec(bazelCommand, ['clean'], {cwd: SELENIUM_DIRECTORY, env: getBazelEnv()});
 }
 
 /**
@@ -133,7 +191,11 @@ async function atomsBuild () {
     BAZEL_WD_ATOMS_INJECT_TARGET,
   ]) {
     log.info(`Running bazel build for ${target}`);
-    await exec('bazel', ['build', target], {cwd: SELENIUM_DIRECTORY});
+    const buildArgs = ['build', target];
+    if (target === BAZEL_ATOMS_TARGET) {
+      buildArgs.push('--', ...BAZEL_ATOMS_EXCLUDED_TARGETS.map((t) => `-${t}`));
+    }
+    await exec(bazelCommand, buildArgs, {cwd: SELENIUM_DIRECTORY, env: getBazelEnv()});
   }
   log.info(`Bazel builds complete`);
 }
@@ -160,12 +222,12 @@ async function atomsCopyAtoms (atomsDir) {
 }
 
 /**
- * leave timestamp to log when atom build occurred.
+ * Record which Selenium revision produced these atoms.
  */
 async function atomsTimestamp () {
-  log.info(`Adding timestamp to atoms build dir`);
+  log.info(`Recording Selenium revision in atoms dir`);
   const {stdout} = await exec('git', ['log', '-n', '1', '--decorate=full'], {cwd: SELENIUM_DIRECTORY});
-  await fs.writeFile(LAST_UPDATE_FILE, Buffer.from(`${new Date()}\n\n${stdout}`));
+  await fs.writeFile(LAST_UPDATE_FILE, Buffer.from(stdout.trimEnd() + '\n'));
 }
 
 export async function importAtoms(shouldClean) {