From 6ab1c68f19c3c586ff933f0b26c3d7cd3b38d6a0 Mon Sep 17 00:00:00 2001 From: carrerasdarren-cell <283775510+carrerasdarren-cell@users.noreply.github.com> Date: Thu, 19 Nov 2026 22:28:41 -0500 Subject: [PATCH 1/3] feat(driver): support the adbHost capability --- packages/driver-lib/README.md | 4 ++ packages/driver-lib/lib/constraints.ts | 3 ++ packages/driver-lib/lib/driver.ts | 8 ++++ packages/driver-lib/test/unit/driver.spec.ts | 40 ++++++++++++++++++++ 4 files changed, 55 insertions(+) diff --git a/packages/driver-lib/README.md b/packages/driver-lib/README.md index e15921d1..97d463ce 100644 --- a/packages/driver-lib/README.md +++ b/packages/driver-lib/README.md @@ -5,6 +5,10 @@ Appium Android Driver is the collection of common primitives used by other Android drivers, like UIA2/Espresso. This driver cannot work as a separate entity. +Use the string capability `appium:adbHost` to select the host running the ADB server, and +`appium:adbPort` to select its port. The legacy name `appium:remoteAdbHost` is deprecated +and takes precedence if both names are supplied, preserving existing sessions' host selection. + ## Examples - [`examples/media-stream-client.mts`](examples/media-stream-client.mts): a Node.js client that decodes the `appium:mediaStream` BiDi events into a local MJPEG HTTP server or an `.mp4` file written by `ffmpeg`. See `mobile: startMediaStream` in the driver docs. diff --git a/packages/driver-lib/lib/constraints.ts b/packages/driver-lib/lib/constraints.ts index ad359816..ab39b7a8 100644 --- a/packages/driver-lib/lib/constraints.ts +++ b/packages/driver-lib/lib/constraints.ts @@ -39,6 +39,9 @@ export const ANDROID_DRIVER_CONSTRAINTS = { adbPort: { isNumber: true, }, + adbHost: { + isString: true, + }, remoteAdbHost: { isString: true, }, diff --git a/packages/driver-lib/lib/driver.ts b/packages/driver-lib/lib/driver.ts index 974cd3d3..59d66222 100644 --- a/packages/driver-lib/lib/driver.ts +++ b/packages/driver-lib/lib/driver.ts @@ -340,6 +340,14 @@ class AndroidDriver Date: Fri, 20 Nov 2026 08:07:50 -0500 Subject: [PATCH 2/3] fix(driver): resolve adbHost without rewriting session capabilities --- packages/driver-lib/README.md | 8 +++--- .../driver-lib/lib/commands/device/utils.ts | 3 ++- packages/driver-lib/lib/constraints.ts | 1 + packages/driver-lib/lib/driver.ts | 22 +++++++++++----- .../test/unit/commands/device.spec.ts | 6 +++++ packages/driver-lib/test/unit/driver.spec.ts | 26 ++++++++++++------- 6 files changed, 45 insertions(+), 21 deletions(-) diff --git a/packages/driver-lib/README.md b/packages/driver-lib/README.md index 97d463ce..e05e684d 100644 --- a/packages/driver-lib/README.md +++ b/packages/driver-lib/README.md @@ -5,9 +5,11 @@ Appium Android Driver is the collection of common primitives used by other Android drivers, like UIA2/Espresso. This driver cannot work as a separate entity. -Use the string capability `appium:adbHost` to select the host running the ADB server, and -`appium:adbPort` to select its port. The legacy name `appium:remoteAdbHost` is deprecated -and takes precedence if both names are supplied, preserving existing sessions' host selection. +## ADB server host + +Set the string capability `appium:adbHost` to the host running the ADB server. +The deprecated `appium:remoteAdbHost` remains supported. If both are set, the +first nonempty value in `appium:adbHost`, then `appium:remoteAdbHost`, is used. ## Examples diff --git a/packages/driver-lib/lib/commands/device/utils.ts b/packages/driver-lib/lib/commands/device/utils.ts index 93e35507..e0cedefd 100644 --- a/packages/driver-lib/lib/commands/device/utils.ts +++ b/packages/driver-lib/lib/commands/device/utils.ts @@ -122,6 +122,7 @@ export async function createBaseADB(this: AndroidDriver): Promise { const { adbPort, suppressKillServer, + adbHost, remoteAdbHost, clearDeviceLogsOnStart, adbExecTimeout, @@ -144,7 +145,7 @@ export async function createBaseADB(this: AndroidDriver): Promise { return await ADB.createADB({ adbPort, suppressKillServer, - remoteAdbHost, + remoteAdbHost: adbHost || remoteAdbHost, clearDeviceLogsOnStart, adbExecTimeout, useKeystore, diff --git a/packages/driver-lib/lib/constraints.ts b/packages/driver-lib/lib/constraints.ts index ab39b7a8..77dea9eb 100644 --- a/packages/driver-lib/lib/constraints.ts +++ b/packages/driver-lib/lib/constraints.ts @@ -42,6 +42,7 @@ export const ANDROID_DRIVER_CONSTRAINTS = { adbHost: { isString: true, }, + /** @deprecated Use adbHost instead. */ remoteAdbHost: { isString: true, }, diff --git a/packages/driver-lib/lib/driver.ts b/packages/driver-lib/lib/driver.ts index 59d66222..7dbe2937 100644 --- a/packages/driver-lib/lib/driver.ts +++ b/packages/driver-lib/lib/driver.ts @@ -340,15 +340,23 @@ class AndroidDriver) { + const result = await super.createSession(w3cCapabilities); + const caps = result[1] as AndroidDriverCaps; + const opts = this.opts as AndroidDriverOpts; + if (caps.remoteAdbHost != null) { this.log.warn("The 'remoteAdbHost' capability is deprecated. Use 'adbHost' instead."); - androidCaps.adbHost = androidCaps.remoteAdbHost; - } else if (androidCaps.adbHost != null) { - // ADB and downstream drivers read this option after BaseDriver copies the validated caps. - androidCaps.remoteAdbHost = androidCaps.adbHost; } - - return true; + const host = caps.adbHost || caps.remoteAdbHost || opts.adbHost || opts.remoteAdbHost; + if (host) { + // Downstream drivers still read remoteAdbHost when connecting to the ADB server. + opts.remoteAdbHost = host; + opts.adbHost = host; + } + return result; } override async getLogTypes(): Promise { diff --git a/packages/driver-lib/test/unit/commands/device.spec.ts b/packages/driver-lib/test/unit/commands/device.spec.ts index e43b0da3..a5a2a3fd 100644 --- a/packages/driver-lib/test/unit/commands/device.spec.ts +++ b/packages/driver-lib/test/unit/commands/device.spec.ts @@ -403,6 +403,12 @@ describe('Device Helpers', function () { assert.strictEqual(curDeviceId, '111222'); assert.strictEqual(emulatorPort, 111); }); + it('should use adbHost from driver options without session capabilities', async function () { + driver.opts.adbHost = 'configured.example'; + driver.opts.remoteAdbHost = 'legacy.example'; + await driver.createADB(); + assert.equal((ADB.createADB as sinon.SinonStub).lastCall.args[0].remoteAdbHost, 'configured.example'); + }); it('should not set emulator port if emPort is undefined', async function () { emulatorPort = 5555; await driver.createADB(); diff --git a/packages/driver-lib/test/unit/driver.spec.ts b/packages/driver-lib/test/unit/driver.spec.ts index 14e3882e..356d929d 100644 --- a/packages/driver-lib/test/unit/driver.spec.ts +++ b/packages/driver-lib/test/unit/driver.spec.ts @@ -6,23 +6,29 @@ import sinon from 'sinon'; import {AndroidDriver} from '../../lib/driver.js'; describe('ADB server host capabilities', function () { - for (const [name, caps, expected] of [ + const cases: [string, {'appium:adbHost'?: string; 'appium:remoteAdbHost'?: string}, string | undefined][] = [ ['adbHost', {'appium:adbHost': 'localhost'}, 'localhost'], ['legacy remoteAdbHost', {'appium:remoteAdbHost': 'legacy.example'}, 'legacy.example'], - ['both names', {'appium:adbHost': 'new.example', 'appium:remoteAdbHost': 'legacy.example'}, 'legacy.example'], + ['both names', {'appium:adbHost': 'new.example', 'appium:remoteAdbHost': 'legacy.example'}, 'new.example'], + ['empty legacy name', {'appium:adbHost': 'new.example', 'appium:remoteAdbHost': ''}, 'new.example'], + ['empty new name', {'appium:adbHost': '', 'appium:remoteAdbHost': 'legacy.example'}, 'legacy.example'], ['neither name', {}, undefined], - ] as const) { - it(`should select the ADB host for ${name}`, async function () { + ]; + for (const [name, caps, expected] of cases) { + it(`should select the ADB host for ${name} and preserve the supplied capabilities`, async function () { const driver = new AndroidDriver(); - const [, sessionCaps] = await driver.createSession({ - alwaysMatch: {platformName: 'Android', 'appium:automationName': 'UiAutomator2'}, - firstMatch: [caps], - }); + const warn = sinon.spy(driver.log, 'warn'); try { + const [, sessionCaps] = await driver.createSession({ + alwaysMatch: {platformName: 'Android', 'appium:automationName': 'UiAutomator2'}, + firstMatch: [caps], + }); assert.equal(driver.opts.remoteAdbHost, expected); - assert.equal(sessionCaps.adbHost, expected); - assert.equal(sessionCaps.remoteAdbHost, expected); + assert.equal(sessionCaps.adbHost, caps['appium:adbHost']); + assert.equal(sessionCaps.remoteAdbHost, caps['appium:remoteAdbHost']); + assert.equal(warn.calledWithMatch(/remoteAdbHost.*deprecated/), 'appium:remoteAdbHost' in caps); } finally { + warn.restore(); await driver.deleteSession(); } }); From f42ba458e8631409c38162cd091247786af056ce Mon Sep 17 00:00:00 2001 From: carrerasdarren-cell <283775510+carrerasdarren-cell@users.noreply.github.com> Date: Sat, 21 Nov 2026 16:46:07 -0500 Subject: [PATCH 3/3] fix(driver): share ADB host resolution with subclasses --- packages/driver-lib/README.md | 11 +++-- .../driver-lib/lib/commands/device/utils.ts | 4 +- packages/driver-lib/lib/driver.ts | 28 +++++------ packages/driver-lib/test/unit/driver.spec.ts | 48 ++++++++++++++++--- 4 files changed, 65 insertions(+), 26 deletions(-) diff --git a/packages/driver-lib/README.md b/packages/driver-lib/README.md index e05e684d..64d92504 100644 --- a/packages/driver-lib/README.md +++ b/packages/driver-lib/README.md @@ -7,9 +7,14 @@ Appium Android Driver is the collection of common primitives used by other Andro ## ADB server host -Set the string capability `appium:adbHost` to the host running the ADB server. -The deprecated `appium:remoteAdbHost` remains supported. If both are set, the -first nonempty value in `appium:adbHost`, then `appium:remoteAdbHost`, is used. +Set the string capability `appium:adbHost` to the host running the ADB server and +`appium:adbPort` to its port. The deprecated `appium:remoteAdbHost` remains +supported. The first nonempty host is used, with `appium:adbHost` preferred over +`appium:remoteAdbHost` and session capabilities preferred over driver defaults. + +Android driver subclasses can use `this.getAdbHost()` to resolve the same host +for their downstream connections, including when they call `BaseDriver.createSession` +directly. The resolver leaves the original session capabilities and options intact. ## Examples diff --git a/packages/driver-lib/lib/commands/device/utils.ts b/packages/driver-lib/lib/commands/device/utils.ts index e0cedefd..f5666451 100644 --- a/packages/driver-lib/lib/commands/device/utils.ts +++ b/packages/driver-lib/lib/commands/device/utils.ts @@ -122,8 +122,6 @@ export async function createBaseADB(this: AndroidDriver): Promise { const { adbPort, suppressKillServer, - adbHost, - remoteAdbHost, clearDeviceLogsOnStart, adbExecTimeout, useKeystore, @@ -145,7 +143,7 @@ export async function createBaseADB(this: AndroidDriver): Promise { return await ADB.createADB({ adbPort, suppressKillServer, - remoteAdbHost: adbHost || remoteAdbHost, + remoteAdbHost: this.getAdbHost(), clearDeviceLogsOnStart, adbExecTimeout, useKeystore, diff --git a/packages/driver-lib/lib/driver.ts b/packages/driver-lib/lib/driver.ts index 7dbe2937..4ce87ff8 100644 --- a/packages/driver-lib/lib/driver.ts +++ b/packages/driver-lib/lib/driver.ts @@ -320,6 +320,10 @@ class AndroidDriver) { - const result = await super.createSession(w3cCapabilities); - const caps = result[1] as AndroidDriverCaps; - const opts = this.opts as AndroidDriverOpts; - if (caps.remoteAdbHost != null) { - this.log.warn("The 'remoteAdbHost' capability is deprecated. Use 'adbHost' instead."); - } - const host = caps.adbHost || caps.remoteAdbHost || opts.adbHost || opts.remoteAdbHost; - if (host) { - // Downstream drivers still read remoteAdbHost when connecting to the ADB server. - opts.remoteAdbHost = host; - opts.adbHost = host; - } - return result; + /** + * Resolves the ADB server host for ADB commands and downstream proxies. + * Session capabilities take precedence over driver defaults. + * + * @returns The configured host, or undefined for a local connection. + */ + getAdbHost(): string | undefined { + const {adbHost, remoteAdbHost} = this.caps as AndroidDriverCaps; + const opts = this.opts as AndroidDriverOpts | undefined; + return adbHost || remoteAdbHost || opts?.adbHost || opts?.remoteAdbHost || undefined; } override async getLogTypes(): Promise { diff --git a/packages/driver-lib/test/unit/driver.spec.ts b/packages/driver-lib/test/unit/driver.spec.ts index 356d929d..b9be0bf5 100644 --- a/packages/driver-lib/test/unit/driver.spec.ts +++ b/packages/driver-lib/test/unit/driver.spec.ts @@ -1,39 +1,75 @@ import assert from 'node:assert/strict'; import {describe, it} from 'node:test'; +import {ADB} from 'appium-adb'; +import {BaseDriver} from 'appium/driver.js'; import sinon from 'sinon'; -import {AndroidDriver} from '../../lib/driver.js'; +import {AndroidDriver, type AndroidDriverOpts, type W3CAndroidDriverCaps} from '../../lib/driver.js'; describe('ADB server host capabilities', function () { + class DirectBaseDriver extends AndroidDriver { + override async createSession(w3cCapabilities: W3CAndroidDriverCaps) { + return await BaseDriver.prototype.createSession.call(this, w3cCapabilities); + } + } + const cases: [string, {'appium:adbHost'?: string; 'appium:remoteAdbHost'?: string}, string | undefined][] = [ ['adbHost', {'appium:adbHost': 'localhost'}, 'localhost'], ['legacy remoteAdbHost', {'appium:remoteAdbHost': 'legacy.example'}, 'legacy.example'], ['both names', {'appium:adbHost': 'new.example', 'appium:remoteAdbHost': 'legacy.example'}, 'new.example'], ['empty legacy name', {'appium:adbHost': 'new.example', 'appium:remoteAdbHost': ''}, 'new.example'], ['empty new name', {'appium:adbHost': '', 'appium:remoteAdbHost': 'legacy.example'}, 'legacy.example'], + ['both names empty', {'appium:adbHost': '', 'appium:remoteAdbHost': ''}, undefined], ['neither name', {}, undefined], ]; for (const [name, caps, expected] of cases) { - it(`should select the ADB host for ${name} and preserve the supplied capabilities`, async function () { - const driver = new AndroidDriver(); + it(`should resolve ${name} consistently after a direct BaseDriver session`, async function () { + const driver = new DirectBaseDriver(); const warn = sinon.spy(driver.log, 'warn'); + const createADB = sinon.stub(ADB, 'createADB').resolves(new ADB()); try { const [, sessionCaps] = await driver.createSession({ - alwaysMatch: {platformName: 'Android', 'appium:automationName': 'UiAutomator2'}, + alwaysMatch: {platformName: 'Android', 'appium:automationName': 'UiAutomator2', 'appium:adbPort': 5038}, firstMatch: [caps], }); - assert.equal(driver.opts.remoteAdbHost, expected); + assert.equal(driver.getAdbHost(), expected); + await driver.createADB(); + assert.equal(createADB.callCount, 1); + assert.equal(createADB.firstCall.args[0]?.remoteAdbHost, expected); + assert.equal(createADB.firstCall.args[0]?.adbPort, 5038); assert.equal(sessionCaps.adbHost, caps['appium:adbHost']); assert.equal(sessionCaps.remoteAdbHost, caps['appium:remoteAdbHost']); - assert.equal(warn.calledWithMatch(/remoteAdbHost.*deprecated/), 'appium:remoteAdbHost' in caps); + assert.equal(driver.opts.adbHost, caps['appium:adbHost']); + assert.equal(driver.opts.remoteAdbHost, caps['appium:remoteAdbHost']); + assert.equal(warn.calledWithMatch(/remoteAdbHost.*deprecated/), Boolean(caps['appium:remoteAdbHost'])); } finally { + createADB.restore(); warn.restore(); await driver.deleteSession(); } }); } + it('should prefer a session host to a driver default supplied under the other name', async function () { + const opts = {adbHost: 'default.example'} as AndroidDriverOpts; + const driver = new DirectBaseDriver(opts); + try { + await driver.createSession({ + alwaysMatch: { + platformName: 'Android', + 'appium:automationName': 'UiAutomator2', + 'appium:remoteAdbHost': 'session.example', + }, + firstMatch: [{}], + }); + assert.equal(driver.getAdbHost(), 'session.example'); + assert.equal(driver.opts.adbHost, 'default.example'); + } finally { + await driver.deleteSession(); + } + }); + it('should reject a non-string adbHost before starting the session', async function () { const driver = new AndroidDriver(); await assert.rejects(