Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions packages/driver-lib/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 1 addition & 2 deletions packages/driver-lib/lib/commands/device/utils.ts
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,6 @@ export async function createBaseADB(this: AndroidDriver): Promise<ADB> {
const {
adbPort,
suppressKillServer,
remoteAdbHost,
clearDeviceLogsOnStart,
adbExecTimeout,
useKeystore,
Expand All @@ -144,7 +143,7 @@ export async function createBaseADB(this: AndroidDriver): Promise<ADB> {
return await ADB.createADB({
adbPort,
suppressKillServer,
remoteAdbHost,
remoteAdbHost: this.getAdbHost(),
clearDeviceLogsOnStart,
adbExecTimeout,
useKeystore,
Expand Down
4 changes: 4 additions & 0 deletions packages/driver-lib/lib/constraints.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,10 @@ export const ANDROID_DRIVER_CONSTRAINTS = {
adbPort: {
isNumber: true,
},
adbHost: {
isString: true,
},
/** @deprecated Use adbHost instead. */
remoteAdbHost: {
Comment thread
mykola-mokhnach marked this conversation as resolved.
Resolved
isString: true,
},
Expand Down
16 changes: 16 additions & 0 deletions packages/driver-lib/lib/driver.ts
Original file line number Diff line number Diff line change
Expand Up @@ -320,6 +320,10 @@ class AndroidDriver<C extends AndroidDriverConstraints = AndroidDriverConstraint
}

const androidCaps = caps as AndroidDriverCaps;
if (androidCaps.remoteAdbHost) {
this.log.warn("The 'remoteAdbHost' capability is deprecated. Use 'adbHost' instead.");
}

if (androidCaps.browserName) {
if (androidCaps.app) {
// warn if the capabilities have both `app` and `browser, although this is common with selenium grid
Expand All @@ -343,6 +347,18 @@ class AndroidDriver<C extends AndroidDriverConstraints = AndroidDriverConstraint
return true;
}

/**
* 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<string[]> {
const nativeLogTypes = await super.getLogTypes();
if (this.isWebContext() && this.chromedriver) {
Expand Down
6 changes: 6 additions & 0 deletions packages/driver-lib/test/unit/commands/device.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down
84 changes: 83 additions & 1 deletion packages/driver-lib/test/unit/driver.spec.ts
Original file line number Diff line number Diff line change
@@ -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 () {
Expand Down