Skip to content

feat(driver): support the adbHost capability - #155

Open
carrerasdarren-cell wants to merge 3 commits into
appium:mainfrom
carrerasdarren-cell:feat/android-adb-host-capability
Open

carrerasdarren-cell wants to merge 3 commits into
appium:mainfrom
carrerasdarren-cell:feat/android-adb-host-capability

Conversation

@carrerasdarren-cell

@carrerasdarren-cell carrerasdarren-cell commented Nov 20, 2026 •

Copy link
Copy Markdown

Addresses appium/appium#9376.

Android sessions can select the ADB server with appium:adbHost. The deprecated appium:remoteAdbHost continues to work and logs a warning when it has a nonempty value. A nonempty adbHost takes precedence when both names are supplied. The session response preserves the capabilities the client sent, and the shared driver uses getAdbHost() for its ADB factory and exposes the same resolver to downstream drivers.

I used OpenAI Codex to implement and test this change. The TypeScript build, repository lint and formatting checks, and all 383 shared Android driver unit tests passed. Eight local checks exercised the real Appium ADB wrapper against a synthetic executable, verifying the selected host, arguments, runtime options and returned capabilities for defaults, aliases, conflicting and empty values, and initial options. Validation was device-free.

Shared host follow-up

The resolver now works when a subclass calls BaseDriver.createSession directly. It leaves session capabilities and runtime options intact. The new tests check that path and verify that the ADB factory and the accessor agree.

UiAutomator2 and Espresso still need to switch their proxy host lookups to getAdbHost() and update their capability docs once a compatible shared-driver version is available. The UiAutomator2 and Espresso dependency checks in this PR exercise the published drivers to the synthetic device-discovery boundary and confirm the shared resolution across 12 cases. The TypeScript build, all 385 shared-driver unit tests, repository lint, and formatting passed on this revision.

@github-actions github-actions Bot added documentation Improvements or additions to documentation enhancement New feature or request package:android-driver labels Nov 20, 2026

@mykola-mokhnach mykola-mokhnach left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • [minor] packages/driver-lib/lib/commands/device/utils.ts:125: createBaseADB still reads only remoteAdbHost, so the new capability works only through the back-copy in validateDesiredCaps. A subclass or code path that sets opts.adbHost any other way (for example initialOpts) gets no -H and falls back to the local ADB server without an error. Consider resolving the host here too (remoteAdbHost: adbHost ?? remoteAdbHost) so the value is chosen at the point where ADB consumes it.
  • [minor] packages/driver-lib/lib/constraints.ts:45: remoteAdbHost is now deprecated, but only a runtime log line says so. Consider a @deprecated note pointing to adbHost, if the constraints or types can carry one.
  • [minor] packages/driver-lib/test/unit/driver.spec.ts: add tests for an empty-string remoteAdbHost, for the deprecation warning, and for adbHost supplied outside the session caps. The current cases only cover the happy paths and the legacy-wins precedence.

Comment thread packages/driver-lib/lib/driver.ts Resolved
Comment thread packages/driver-lib/lib/driver.ts Resolved
Comment thread packages/driver-lib/lib/driver.ts Resolved
Comment thread packages/driver-lib/lib/driver.ts Resolved
Comment thread packages/driver-lib/README.md Outdated

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nit] This text says the deprecated name "takes precedence", which reads as the opposite of the migration advice. adbPort is existing, unchanged behaviour, so it doesn't belong in this feature's note. This intro paragraph is also an odd home for capability documentation, and there is no changelog or capability-docs entry for the new capability.

Comment thread packages/driver-lib/lib/constraints.ts Resolved

@mykola-mokhnach mykola-mokhnach left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • [minor] Tests only exercise a bare AndroidDriver.createSession (test/unit/driver.spec.ts). A subclass that calls BaseDriver.prototype.createSession directly (as UIA2 does) would leave opts.remoteAdbHost unset and still pass. After the fix for the createSession comment, please add a test for that path.
  • [minor] Docs: the README note is in driver-lib only. appium-uiautomator2-driver (docs/reference/capabilities.md:443) and the Espresso docs still describe only appium:remoteAdbHost. Is a follow-up planned there?
  • [nit] caps.remoteAdbHost != null (driver.ts:351) also warns for remoteAdbHost: '', which carries no host. Consider a truthiness check.

Comment thread packages/driver-lib/lib/driver.ts Outdated
return true;
}

override async createSession(w3cCapabilities: W3CDriverCaps<C>) {

@mykola-mokhnach mykola-mokhnach Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[major] This override never runs for the UiAutomator2 driver. Its createSession calls BaseDriver.prototype.createSession.call(this, …) (appium-uiautomator2-driver master, lib/driver.ts:297), which skips AndroidDriver.createSession. A UIA2 client that sends only appium:adbHost: 'remote' gets ADB pointed at remote (createBaseADB does adbHost || remoteAdbHost). Meanwhile opts.remoteAdbHost stays unset, and UIA2 builds the server client host from it (lib/uiautomator2-server/session.ts:343: this.opts.remoteAdbHost || LOCALHOST_IP4). ADB talks to the remote host while the server client targets localhost, so the session fails or talks to the wrong machine once UIA2 picks up this driver-lib version. Espresso calls super.createSession and is unaffected by the bypass, but it also reads only opts.remoteAdbHost (lib/commands/server/startup.ts:150).

Resolving the host in one place that every driver reaches would be sturdier, for example a shared getAdbHost() helper in driver-lib. UIA2/Espresso would read that instead of opts.remoteAdbHost, and the post-hoc mutation of opts would go away. Otherwise the normalization needs to live somewhere UIA2 can't bypass.

Comment thread packages/driver-lib/lib/driver.ts Outdated
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;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[minor] The adbHost-over-remoteAdbHost precedence is implemented twice, here and in createBaseADB. The two copies already differ: here it's caps.adbHost || caps.remoteAdbHost || opts.adbHost || opts.remoteAdbHost, there it's opts only. Because this override can be skipped (see above), they can return different hosts for the same session. Please route both through one helper.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request package:android-driver

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants