diff --git a/packages/driver-lib/README.md b/packages/driver-lib/README.md index e15921d..64d9250 100644 --- a/packages/driver-lib/README.md +++ b/packages/driver-lib/README.md @@ -5,6 +5,17 @@ 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. +## ADB server host + +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 - [`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/commands/device/utils.ts b/packages/driver-lib/lib/commands/device/utils.ts index 93e3550..f566645 100644 --- a/packages/driver-lib/lib/commands/device/utils.ts +++ b/packages/driver-lib/lib/commands/device/utils.ts @@ -122,7 +122,6 @@ export async function createBaseADB(this: AndroidDriver): Promise { const { adbPort, suppressKillServer, - remoteAdbHost, clearDeviceLogsOnStart, adbExecTimeout, useKeystore, @@ -144,7 +143,7 @@ export async function createBaseADB(this: AndroidDriver): Promise { return await ADB.createADB({ adbPort, suppressKillServer, - remoteAdbHost, + remoteAdbHost: this.getAdbHost(), clearDeviceLogsOnStart, adbExecTimeout, useKeystore, diff --git a/packages/driver-lib/lib/constraints.ts b/packages/driver-lib/lib/constraints.ts index ad35981..77dea9e 100644 --- a/packages/driver-lib/lib/constraints.ts +++ b/packages/driver-lib/lib/constraints.ts @@ -39,6 +39,10 @@ export const ANDROID_DRIVER_CONSTRAINTS = { adbPort: { isNumber: true, }, + 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 974cd3d..4ce87ff 100644 --- a/packages/driver-lib/lib/driver.ts +++ b/packages/driver-lib/lib/driver.ts @@ -320,6 +320,10 @@ class AndroidDriver { const nativeLogTypes = await super.getLogTypes(); if (this.isWebContext() && this.chromedriver) { diff --git a/packages/driver-lib/test/unit/commands/device.spec.ts b/packages/driver-lib/test/unit/commands/device.spec.ts index e43b0da..a5a2a3f 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 4703e5c..b9be0bf 100644 --- a/packages/driver-lib/test/unit/driver.spec.ts +++ b/packages/driver-lib/test/unit/driver.spec.ts @@ -1,9 +1,91 @@ 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 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', 'appium:adbPort': 5038}, + firstMatch: [caps], + }); + 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(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( + driver.createSession({ + alwaysMatch: { + platformName: 'Android', + 'appium:automationName': 'UiAutomator2', + // @ts-expect-error Exercise runtime validation of a malformed client request. + 'appium:adbHost': ['localhost'], + }, + }), + /adbHost.*string/i, + ); + assert.equal(driver.sessionId, null); + }); +}); describe('AndroidDriver inheritance', function () { it('should attach commands to the prototype', function () {