Skip to content

feat(install): let install() and installRemote() take pm install flags - #595

Merged
koral-- merged 3 commits into
masterfrom
feat/install-options
Nov 20, 2026
Merged

koral-- merged 3 commits into
masterfrom
feat/install-options

Conversation

@koral--

@koral-- koral-- commented Nov 20, 2026

Copy link
Copy Markdown
Member

Closes #239

device.install() and device.installRemote() always ran pm install -r <apk>, so there was no way to downgrade an app (-d), grant its runtime permissions (-g) or install a test-only apk (-t). Both now take an optional InstallOptions object. Without it, the command is still exactly pm install -r <apk>.

// pm install -r -d -g <apk>
await device.install('app.apk', { allowDowngrade: true, grantPermissions: true });

// pm install -t "--user" "10" <apk>
await device.installRemote('/data/local/tmp/app.apk', {
  reinstall: false,
  allowTestPackages: true,
  args: ['--user', '10'],
});
  • allowDowngrade, grantPermissions and allowTestPackages add -d, -g and -t. They're all off by default.
  • reinstall defaults to true. reinstall: false leaves out -r.
  • args passes any other pm install arguments. Each one is quoted with the same helper as the apk path, so it stays a single argument and can't run another shell command.
  • Anything other than an object as the second argument means no options. That covers a callback, which the README used to list for both methods, and null.
  • The README and JSDoc now describe the options and the rejection. The stale callback bullets are removed from both methods.

On the first part of the issue: a failed install already rejects in a way the caller can catch, with an Error whose code holds the device's reason. The emulator run below confirms it.

Testing

  • npm run lint, npm run compile and npm test pass (390 passing).
  • The unit tests cover:
    • the exact command for no options, {}, each flag, every flag at once, reinstall: false, args, and escaping of spaces, $( ), backticks, " and \;
    • a callback or null passed as options;
    • install() handing its options to installRemote(), and installRemote() sending them and still removing the apk.
  • Mutation check: I reverted each piece on its own and confirmed a test fails. That covers each flag, -r always on, -r always off, args ignored, args unescaped, the object guard, both forwardings, and flag order.
  • Built library against an Android 16 (API 36, user build) emulator through the local adb server:
    • install(v2) installed with CAMERA not granted. install(v2, { grantPermissions: true }) installed with CAMERA granted.
    • install(v1) over v2 rejected with err.code = INSTALL_FAILED_VERSION_DOWNGRADE: Downgrade detected: ..., caught in a try/catch.
    • install(v1, { allowDowngrade: true }) installed version 1 over version 2 for a debuggable app. For a non-debuggable app, this user build still refused it, as the docs now say.
    • A testOnly apk was rejected with INSTALL_FAILED_TEST_ONLY without -t, and installed with allowTestPackages: true.
    • args: ['--user', '0'] installed. args: ['--user', '0; touch /data/local/tmp/pwned'] reached pm as one argument (Bad user number: 0; touch /data/local/tmp/pwned), and no file was created.
    • reinstall: false over an installed app still succeeded, because Android 16 replaces the app without -r. The docs say so.

🤖 Generated with Claude Code

koral-- and others added 3 commits November 20, 2026 19:40
install() and installRemote() always ran pm install -r <apk>, so there
was no way to downgrade an app (-d), grant its runtime permissions (-g)
or install a test-only apk (-t). Both now take an optional InstallOptions
object: allowDowngrade, grantPermissions and allowTestPackages add -d,
-g and -t, reinstall: false leaves out -r, and args passes anything else,
each quoted like the apk path. Without options the command is still
exactly pm install -r <apk>. Anything but an object, such as a callback
the README used to list, means no options.

Closes #239

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
…or showed them

On Android 16 the device reports a failure as
[INSTALL_FAILED_VERSION_DOWNGRADE: Downgrade detected: ...], so the
error's code starts with the reason code instead of being only that.
The same device also replaces an installed app without -r, so
reinstall: false makes no difference there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
- Check options before anything is sent. An array as options, or args
  that isn't an array of strings, now rejects with a TypeError and ends
  the connection; before, it threw synchronously, so installRemote()
  left the temp apk on the device and the socket open.
- Single-quote args, as startActivity() does, so '!' reaches pm
  unchanged instead of as '\!'.
- Docs: replacing is the default, not a given (reinstall: false); an
  unknown flag on older Android rejects without .code; the TypeError.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Karol Wrótniak <karol.wrotniak@droidsonroids.pl>
@koral--
koral-- merged commit 75a327b into master Nov 20, 2026
6 checks passed
@koral--
koral-- deleted the feat/install-options branch November 20, 2026 19:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant