appium-espresso-driver 8.5.5 → 8.6.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [8.6.0](https://github.com/appium/appium-espresso-driver/compare/v8.5.6...v8.6.0) (2026-05-24)
+
+### Features
+
+* Add a script for app diagnosis ([#1175](https://github.com/appium/appium-espresso-driver/issues/1175)) ([c2b48e8](https://github.com/appium/appium-espresso-driver/commit/c2b48e828d8595c90cba4e5222e21485f99b686d))
+
+## [8.5.6](https://github.com/appium/appium-espresso-driver/compare/v8.5.5...v8.5.6) (2026-05-23)
+
+### Miscellaneous Chores
+
+* **deps:** bump composeUiTest from 1.1.1 to 1.11.2 in /espresso-server ([#1170](https://github.com/appium/appium-espresso-driver/issues/1170)) ([417a42a](https://github.com/appium/appium-espresso-driver/commit/417a42a05e1dedcef3c56babd0ca21d492da0b38))
+
 ## [8.5.5](https://github.com/appium/appium-espresso-driver/compare/v8.5.4...v8.5.5) (2026-05-23)
 
 ### Miscellaneous Chores

package/README.md

@@ -239,6 +239,8 @@ The `swiper` argument is not supported in Compose mode. Available since driver v
 
 Calling other driver element-specific APIs not listed above would most likely throw an exception as Compose and Espresso elements are being stored in completely separated internal caches and must not be mixed.
 
+If session startup or Compose interactions fail, see [How To Troubleshoot Jetpack Compose Apps](docs/compose-troubleshooting.md).
+
 You could also check end-to-end tests for more examples on how to setup test capabilities and
 on the Compose usage in general:
 - https://github.com/appium/appium-espresso-driver/blob/master/test/functional/commands/jetpack-componse-element-values-e2e-specs.js
@@ -1830,6 +1832,8 @@ more details.
 
 ## Troubleshooting
 
+* Run `appium driver run espresso diagnose-app --app /path/to/your/android-project` or `--app /path/to/debug.apk`. The script checks manifest permissions, obfuscation, AndroidX/Compose dependency alignment, and other static preconditions for precompile. Exit code is non-zero when the app is not ready for precompile.
+* If you test **Jetpack Compose** apps (or hybrid View + Compose UIs) and see server startup failures, `NoSuchMethodError` in `androidx.compose.*`, misleading `INTERNET` permission errors, `InitializationProvider` / `Resources$NotFoundException`, or locator issues in `compose` subdriver mode, read [How To Troubleshoot Jetpack Compose Apps](docs/compose-troubleshooting.md).
 * If you observe Espresso server crash on startup and various exceptions about missing class/method in the logcat output then consider updating [appium:espressoBuildConfig](#espresso-build-config) capability with module versions that match your application under test. This might require some experimentation, as different apps have different module requirements. Check, for example, [issue #812](https://github.com/appium/appium-espresso-driver/issues/812). Another solution might be
 to [integrate](#consuming-espresso-server-as-library) Espresso Server with the application under test in form of a library.
 * If you experience issues with application activities being not found or not starting then consider checking [How To Troubleshoot Activities Startup](docs/activity-startup.md) article.
@@ -1851,8 +1855,6 @@ to [integrate](#consuming-espresso-server-as-library) Espresso Server with the a
   -keep class android.support.v7.** { *; }
   ```
   Please read [#449](https://github.com/appium/appium-espresso-driver/issues/449#issuecomment-537833139) for more details on this topic.
-* When you want to build without compose dependencies
-    * Espresso driver has Jetpack Compose dependencies to [support Jetpack Compose](#jetpack-compose-support). It could break the application under test's dependencies. The typical case is when the application under test does not have the Jetpack Compose dependencies. Then, you can try out [no compose dependencies branch](https://github.com/appium/appium-espresso-driver/pull/879)). In Appium 2.0, the branch is available as `appium driver install --source=local /path/to/the/appium-espress-driver` with the `no-compose-deps` branch instead of npm installation.
 
 
 ## Contributing

package/espresso-server/buildSrc/.gradle/buildOutputCleanup/cache.properties

@@ -1,2 +1,2 @@
-#Sat May 23 10:02:06 UTC 2026
+#Sun May 24 16:52:48 UTC 2026
 gradle.version=9.5.1

package/espresso-server/gradle/libs.versions.toml

@@ -3,7 +3,7 @@ androidGradlePlugin = "9.2.1"
 kotlin = "2.3.21"
 androidxTest = "1.7.0"
 annotation = "1.10.0"
-composeUiTest = "1.1.1"
+composeUiTest = "1.11.2"
 gson = "2.14.0"
 espresso = "3.7.0"
 nanohttpd = "2.3.1"

package/espresso-server/gradle.properties

@@ -25,7 +25,7 @@ org.gradle.caching=true
 # https://youtrack.jetbrains.com/issue/KT-46708
 kotlin.stdlib.default.dependency=false
 
-appiumCompileSdk=34
+appiumCompileSdk=35
 appiumMinSdk=26
 appiumTargetSdk=34
 appiumBuildTools=36.0.0

package/espresso-server/library/src/main/java/io/appium/espressoserver/lib/helpers/Version.kt

@@ -2,6 +2,6 @@ package io.appium.espressoserver.lib.helpers
 
 // This value is updated automatically by the NPM versioning script
 // It should be in sync with the NPM module version from package.json
-private const val VERSION = "8.5.5"
+private const val VERSION = "8.6.0"
 
 fun getEspressoServerVersion() = VERSION

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-espresso-driver",
-  "version": "8.5.5",
+  "version": "8.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-espresso-driver",
-      "version": "8.5.5",
+      "version": "8.6.0",
       "license": "Apache-2.0",
       "dependencies": {
         "appium-adb": "^15.0.0",

package/package.json

@@ -7,7 +7,7 @@
     "automated testing",
     "android"
   ],
-  "version": "8.5.5",
+  "version": "8.6.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -35,7 +35,8 @@
     "mainClass": "EspressoDriver",
     "scripts": {
       "print-espresso-path": "./scripts/print-espresso-path.mjs",
-      "build-espresso": "./scripts/build-espresso.mjs"
+      "build-espresso": "./scripts/build-espresso.mjs",
+      "diagnose-app": "./scripts/diagnose-app.mjs"
     },
     "doctor": {
       "checks": [

package/scripts/build-espresso.mjs

@@ -1,12 +1,14 @@
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
+import {fileURLToPath, pathToFileURL} from 'node:url';
 import {Command} from 'commander';
 import {logger, fs} from 'appium/support.js';
-import {ServerBuilder} from '../build/lib/commands/server/index.js';
 
 const LOG = logger.getLogger('EspressoBuild');
 
 const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SERVER_BUILDER_MODULE = pathToFileURL(
+  path.join(ROOT_DIR, 'build/lib/commands/server/index.js'),
+).href;
 const ESPRESSO_SERVER_ROOT = path.join(ROOT_DIR, 'espresso-server');
 const ESPRESSO_SERVER_BUILD = path.join(ESPRESSO_SERVER_ROOT, 'app', 'build');
 
@@ -16,6 +18,7 @@ const ESPRESSO_SERVER_BUILD = path.join(ESPRESSO_SERVER_ROOT, 'app', 'build');
 async function buildEspressoServer(options) {
   LOG.info(`Building espresso server in '${ESPRESSO_SERVER_BUILD}'`);
 
+  /** @type {import('../lib/commands/server/builder.js').ServerBuilderOptions} */
   const opts = {
     serverPath: ESPRESSO_SERVER_ROOT,
     showGradleLog: options.showGradleLog,
@@ -43,6 +46,7 @@ async function buildEspressoServer(options) {
     }
   }
 
+  const {ServerBuilder} = await import(SERVER_BUILDER_MODULE);
   const builder = new ServerBuilder(LOG, opts);
   try {
     await builder.build();

package/scripts/diagnose-app.mjs

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {access} from 'node:fs/promises';
+import {constants as fsConstants} from 'node:fs';
+import {Command} from 'commander';
+import {logger} from 'appium/support.js';
+import {
+  collectAppInputFromApk,
+  collectAppInputFromProject,
+  formatDiagnosisReport,
+  loadEspressoServerDefaults,
+  runDiagnosis,
+} from './lib/diagnose/index.mjs';
+
+const LOG = logger.getLogger('EspressoDiagnose');
+
+const ROOT_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ESPRESSO_SERVER_ROOT = path.join(ROOT_DIR, 'espresso-server');
+
+/**
+ * @param {string} targetPath
+ */
+async function pathExists(targetPath) {
+  try {
+    await access(targetPath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} inputPath
+ */
+async function resolveAppInput(inputPath) {
+  const resolved = path.resolve(inputPath);
+  if (!(await pathExists(resolved))) {
+    throw new Error(`Path does not exist: ${resolved}`);
+  }
+  if (resolved.endsWith('.apk')) {
+    return collectAppInputFromApk(resolved);
+  }
+  if (resolved.endsWith('.aab')) {
+    throw new Error('Only .apk files are supported for binary analysis. Use the Gradle project root for .aab.');
+  }
+  return collectAppInputFromProject(resolved);
+}
+
+async function main() {
+  const program = new Command();
+  program
+    .name('appium driver run espresso diagnose-app')
+    .description(
+      'Diagnose whether an Android app is ready to embed a precompiled Espresso server',
+    )
+    .requiredOption(
+      '--app <path>',
+      'Gradle project root of the AUT, or path to a built .apk (debug APK recommended)',
+    )
+    .action(async (options) => {
+      const [appInput, serverDefaults] = await Promise.all([
+        resolveAppInput(options.app),
+        loadEspressoServerDefaults(ESPRESSO_SERVER_ROOT, ROOT_DIR),
+      ]);
+      const report = await runDiagnosis(appInput, serverDefaults);
+
+      LOG.info(`App: ${appInput.kind} at ${appInput.path}`);
+      LOG.info(`Driver: appium-espresso-driver@${serverDefaults.driverVersion}`);
+      if (appInput.sources?.length) {
+        LOG.info(
+          `Scanned: ${appInput.sources.slice(0, 8).join(', ')}${appInput.sources.length > 8 ? '…' : ''}`,
+        );
+      }
+      LOG.info('');
+      LOG.info(formatDiagnosisReport(report));
+      if (!report.ready) {
+        process.exitCode = 1;
+      }
+    });
+
+  await program.parseAsync(process.argv);
+}
+
+await main();

package/scripts/lib/dependency-versions/apk-dex.mjs

@@ -0,0 +1,87 @@
+import {fs, zip} from 'appium/support.js';
+import path from 'node:path';
+
+/**
+ * @param {string} apkPath
+ * @param {string} destDir
+ */
+export async function extractApk(apkPath, destDir) {
+  try {
+    await zip.extractAllTo(apkPath, destDir);
+  } catch (err) {
+    throw new Error(`Failed to extract APK.`, {cause: err});
+  }
+}
+
+/**
+ * @param {string} extractRoot
+ * @returns {Promise<string>}
+ */
+export async function readAllDexStrings(extractRoot) {
+  /** @type {string[]} */
+  const chunks = [];
+  let entries;
+  try {
+    entries = await fs.readdir(extractRoot);
+  } catch {
+    return '';
+  }
+  for (const name of entries) {
+    if (!/^classes\d*\.dex$/i.test(name)) {
+      continue;
+    }
+    try {
+      const buf = await fs.readFile(path.join(extractRoot, name));
+      chunks.push(buf.toString('latin1'));
+    } catch {
+      // ignore
+    }
+  }
+  return chunks.join('\n');
+}
+
+/**
+ * @param {string} dexStrings
+ * @param {string} corpus
+ * @returns {boolean}
+ */
+export function detectProguardLikely(dexStrings, corpus) {
+  const androidxHits = (corpus.match(/androidx\//g) ?? []).length;
+  const hasR8 = /\bR8\b/.test(corpus) || /proguard/i.test(corpus);
+  const fewReadableAndroidx = androidxHits < 3 && dexStrings.length > 100_000;
+  const obfuscatedKotlin = (dexStrings.match(/\bL[a-z]{1,2}\/[a-z]{1,2};/g) ?? []).length > 500;
+  return (hasR8 && fewReadableAndroidx) || (obfuscatedKotlin && fewReadableAndroidx);
+}
+
+/**
+ * @param {string} root
+ * @returns {Promise<string>}
+ */
+export async function collectMetaInfStrings(root) {
+  const metaDir = path.join(root, 'META-INF');
+  /** @type {string[]} */
+  const chunks = [];
+  /** @param {string} dir */
+  async function walkMeta(dir) {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, {withFileTypes: true});
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walkMeta(full);
+      } else if (/\.(properties|version|kotlin_module|txt)$/i.test(entry.name)) {
+        try {
+          chunks.push(await fs.readFile(full, 'utf8'));
+        } catch {
+          // ignore binary
+        }
+      }
+    }
+  }
+  await walkMeta(metaDir);
+  return chunks.join('\n');
+}

package/scripts/lib/dependency-versions/apk-kotlin-metadata.mjs

@@ -0,0 +1,70 @@
+import {fs} from 'appium/support.js';
+import {ADB} from 'appium-adb';
+import path from 'node:path';
+import {exec} from 'teen_process';
+import {normalizeVersion} from './version-utils.mjs';
+
+/** @type {Promise<import('appium-adb').ADB> | undefined} */
+let sdkAdbPromise;
+
+/**
+ * @param {string} dexdumpOutput
+ * @returns {string[]}
+ */
+export function parseKotlinMetadataVersionsFromDexdump(dexdumpOutput) {
+  /** @type {Set<string>} */
+  const versions = new Set();
+  const mvPattern = /mv=\{\s*(\d+)\s+(\d+)\s+(\d+)\s*\}/g;
+  let match;
+  while ((match = mvPattern.exec(dexdumpOutput)) !== null) {
+    const version = normalizeVersion(`${match[1]}.${match[2]}.${match[3]}`);
+    if (version) {
+      versions.add(version);
+    }
+  }
+  return [...versions];
+}
+
+/**
+ * @param {string} extractRoot APK extract directory
+ * @param {Record<string, Set<string>>} found Module id → version set (mutated)
+ */
+export async function mergeKotlinMetadataVersionsFromDex(extractRoot, found) {
+  if (!found.kotlin) {
+    return;
+  }
+  let dexdump;
+  try {
+    const adb = await getSdkAdb();
+    dexdump = await adb.getSdkBinaryPath('dexdump');
+  } catch {
+    return;
+  }
+  let entries;
+  try {
+    entries = await fs.readdir(extractRoot);
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (!/^classes\d*\.dex$/i.test(name)) {
+      continue;
+    }
+    try {
+      const {stdout} = await exec(dexdump, ['-a', path.join(extractRoot, name)]);
+      for (const version of parseKotlinMetadataVersionsFromDexdump(stdout)) {
+        found.kotlin.add(version);
+      }
+    } catch {
+      // try next dex file
+    }
+  }
+}
+
+/** @returns {Promise<import('appium-adb').ADB>} */
+async function getSdkAdb() {
+  if (!sdkAdbPromise) {
+    sdkAdbPromise = ADB.createADB({suppressKillServer: true});
+  }
+  return sdkAdbPromise;
+}

package/scripts/lib/dependency-versions/apk-meta-inf.mjs

@@ -0,0 +1,70 @@
+import {fs} from 'appium/support.js';
+import path from 'node:path';
+import {normalizeVersion} from './version-utils.mjs';
+
+/** @type {ReadonlyArray<{moduleId: string, matches: (base: string) => boolean}>} */
+const META_INF_VERSION_MODULE_RULES = [
+  {moduleId: 'compose', matches: (base) => base.startsWith('androidx.compose.')},
+  {moduleId: 'kotlin', matches: (base) => base.startsWith('org.jetbrains.kotlin_')},
+  {moduleId: 'espresso', matches: (base) => base.startsWith('androidx.test.espresso')},
+  {
+    moduleId: 'annotation',
+    matches: (base) =>
+      base.startsWith('androidx.annotation_annotation') && !base.includes('experimental'),
+  },
+  {moduleId: 'uiautomator', matches: (base) => base.startsWith('androidx.test.uiautomator')},
+  {
+    moduleId: 'androidxTest',
+    matches: (base) =>
+      base.startsWith('androidx.test.') &&
+      !base.startsWith('androidx.test.espresso') &&
+      !base.startsWith('androidx.test.uiautomator'),
+  },
+];
+
+/**
+ * @param {string} base Basename without `.version` (e.g. `androidx.compose.ui_ui`)
+ * @returns {string | null}
+ */
+export function mapMetaInfVersionBaseToModule(base) {
+  for (const {moduleId, matches} of META_INF_VERSION_MODULE_RULES) {
+    if (matches(base)) {
+      return moduleId;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} extractRoot APK extract directory
+ * @param {Record<string, Set<string>>} found Module id → version set (mutated)
+ */
+export async function mergeMetaInfEmbeddedVersions(extractRoot, found) {
+  const metaDir = path.join(extractRoot, 'META-INF');
+  let versionFiles;
+  try {
+    versionFiles = await fs.glob('**/*.version', {cwd: metaDir, absolute: true});
+  } catch {
+    return;
+  }
+  for (const filePath of versionFiles) {
+    const base = path.basename(filePath, '.version');
+    let raw;
+    try {
+      raw = (await fs.readFile(filePath, 'utf8')).trim();
+    } catch {
+      continue;
+    }
+    if (!raw || /writeVersionFile|^\s*task\s*:/i.test(raw)) {
+      continue;
+    }
+    const version = normalizeVersion(raw);
+    if (!version) {
+      continue;
+    }
+    const moduleId = mapMetaInfVersionBaseToModule(base);
+    if (moduleId && found[moduleId]) {
+      found[moduleId].add(version);
+    }
+  }
+}

package/scripts/lib/dependency-versions/apk-scan.mjs

@@ -0,0 +1,35 @@
+import {fs, tempDir} from 'appium/support.js';
+import {createEmptyVersionSets} from './tracked-modules.mjs';
+import {collectVersionsFromCorpus, versionSetsToSortedRecords} from './version-utils.mjs';
+import {extractApk, readAllDexStrings, detectProguardLikely, collectMetaInfStrings} from './apk-dex.mjs';
+import {mergeMetaInfEmbeddedVersions} from './apk-meta-inf.mjs';
+import {mergeKotlinMetadataVersionsFromDex} from './apk-kotlin-metadata.mjs';
+
+/**
+ * @param {string} apkPath
+ * @returns {Promise<{versions: Record<string, string[]>, proguardLikely: boolean, sources: string[]}>}
+ */
+export async function collectAppVersionsFromApk(apkPath) {
+  const extractDir = await tempDir.openDir();
+  try {
+    await extractApk(apkPath, extractDir);
+    const dexStrings = await readAllDexStrings(extractDir);
+    const metaStrings = await collectMetaInfStrings(extractDir);
+    const found = createEmptyVersionSets();
+    const corpus = `${dexStrings}\n${metaStrings}`;
+
+    collectVersionsFromCorpus(corpus, found);
+    await mergeMetaInfEmbeddedVersions(extractDir, found);
+    await mergeKotlinMetadataVersionsFromDex(extractDir, found);
+
+    const proguardLikely = detectProguardLikely(dexStrings, corpus);
+
+    return {
+      versions: versionSetsToSortedRecords(found),
+      proguardLikely,
+      sources: ['APK DEX/META-INF scan (incl. embedded *.version metadata)'],
+    };
+  } finally {
+    await fs.rimraf(extractDir);
+  }
+}