feat: add skipSettingsAppInstall capability to skip installing the Settings helper app

[AsijitM]

Problem

initDevice unconditionally installs the Appium Settings helper app via pushSettingsApp:

const shouldThrowError = Boolean(language || locale || ... || !skipUnlock);
await pushSettingsApp.bind(this)(shouldThrowError);

Some environments already provision the Settings helper app as part of a managed device
image / device farm. In those setups, re-pushing it on every session is redundant work and
can be undesirable (extra installs, timing, or immutable-image constraints).

There is already skipDeviceInitialization to skip the whole init block, but that is too
coarse — it also skips locale/logcat/geolocation setup. There is no way to keep device
initialization while skipping only the Settings app install.

Fix

Add an opt-in boolean capability skipSettingsAppInstall. When set, initDevice skips the
pushSettingsApp call and logs that Settings-app-dependent features may be unavailable. All
other initialization still runs.

• Defaults to false → no behavior change for existing users.
• Follows the existing capability pattern in this driver (e.g. chromedriverGrantPermissions,
  skipDeviceInitialization).

Changes

• lib/constraints.ts: add skipSettingsAppInstall: { isBoolean: true }.
• lib/commands/device/common.ts: guard the pushSettingsApp call with the new capability.

Notes

• Happy to add docs and a unit test if maintainers are on board with the capability.

[AsijitM]

Thanks — and I think the installOrUpgrade behavior is actually the reason the skip is needed, rather than a reason it isn't.

The setup this targets is a managed device farm: the host provisions io.appium.settings itself during device setup and pins a specific version of it, and that app is the session's mock-location provider. The driver bundles its own io.appium.settings version, so when the two differ, installOrUpgrade doesn't no-op — it takes the upgrade branch and reinstalls the app mid-session. In our case that has two concrete consequences:

1. it overrides the host-pinned version with the driver's bundled one, and
2. reinstalling io.appium.settings breaks the active mock-location flow for the session.

So pushSettingsApp isn't redundant work here — it's disruptive precisely in the "a different version is already installed" branch. skipDeviceInitialization is too coarse to help (it also drops locale/logcat/geolocation init), so today there's no way to keep device init while leaving a host-managed Settings app untouched.

That's the gap skipSettingsAppInstall fills — opt-in, default false, so no change for anyone who doesn't manage the app themselves. Happy to reword the cap doc to make the "host owns/pins the Settings helper" intent explicit and add a unit test if you're good with the direction.

[mykola-mokhnach]

Lets not enumerate features as the list may change

[AsijitM]

Done — dropped the enumerated feature list; the new log message no longer names specific features.

[mykola-mokhnach]

should we also alter the below code? Some of it is going to fail if Settings app is not installed

[AsijitM]

Good catch. Addressed by requiring the app to be present when the cap is set: it now checks adb.isAppInstalled(SETTINGS_HELPER_ID) and throws a clear error if it's missing, so the setMockLocationApp / ensureDeviceLocale / keyboard setup below are guaranteed a present Settings app instead of failing opaquely.

[KazuCocoa]

What about tweaking this to "skipSettingsAppReinstall"?
Then, it will raise exception in case the device doesn't have settings app. It will not "install" or "reinstall" settings app but check if the device has settings app

[AsijitM]

@KazuCocoa adopted, thanks — renamed the capability to skipSettingsAppReinstall, and when it's set the driver now verifies the Settings app is present (adb.isAppInstalled) and raises a clear error if it isn't, installing/reinstalling nothing. Added unit tests for both the present (no reinstall) and absent (throws) cases. Agreed this is cleaner than the silent skip.

[KazuCocoa]

lg, thank you!

We'll merge after fixing the conflict

[AsijitM]

@KazuCocoa @mykola-mokhnach I have resolved the conflicts now.

[github-actions]

🎉 This PR is included in version 13.4.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀