Introduction

INSTALL_FAILED_TEST_ONLY means Android rejected an APK marked as test-only during installation. This usually happens with debug builds or CI artifacts that carry testOnly metadata. The fix is quick for local testing, but you should also make build outputs explicit so test artifacts never leak into release workflows.

Why Android Blocks Test-Only Packages

Android package installer enforces safeguards for packages intended only for testing. When an APK is marked test-only, normal install command without test allowance is rejected.

Typical triggers:

• debug variants with test flags
• instrumentation-oriented build tasks
• custom manifest merge settings
• CI pipelines reusing internal test artifacts

This protection is intentional and helps prevent accidental deployment of non-production packages.

Confirm the APK Metadata

Check whether APK contains test-only flag before changing commands.

aapt dump badging app-debug.apk | grep testOnly

If output includes testOnly=true, plain install will fail.

Also check package name and version metadata:

aapt dump badging app-debug.apk | grep package

This helps catch accidental wrong artifact selection.

Quick Local Fix: Install with -t

For development devices and emulators, allow test-only install explicitly.

adb install -t app-debug.apk

For reinstall over existing package:

adb install -r -t app-debug.apk

Use this for local iteration, QA test beds, and integration test devices.

Correct Fix for Distribution Artifacts

If artifact should install without -t, generate proper non-test build.

./gradlew assembleRelease
adb install app-release.apk

Release pipelines should never depend on test-only bypass flags. If they do, artifact promotion policy is broken.

Check Build Variant and Signing Flow

Many teams hit this error because scripts build one variant and attempt to distribute another. Verify build command and output path alignment.

1./gradlew :app:assembleDebug
2ls app/build/outputs/apk/debug/
3
4./gradlew :app:assembleRelease
5ls app/build/outputs/apk/release/

Also verify signing config for release variant in Gradle setup.

Device-Side Cleanup During Troubleshooting

Sometimes stale package state confuses installation attempts. Reset state when needed.

1adb devices
2adb shell pm list packages | grep your.package.name
3adb uninstall your.package.name
4adb install -t app-debug.apk

This separates test-only rejection from unrelated package conflicts.

CI Pipeline Hardening Pattern

A robust pipeline should detect test-only metadata and choose install strategy intentionally.

1APK_PATH="app/build/outputs/apk/debug/app-debug.apk"
2
3if aapt dump badging "$APK_PATH" | grep -q "testOnly=true"; then
4  adb install -r -t "$APK_PATH"
5else
6  adb install -r "$APK_PATH"
7fi

Better still, split jobs by artifact type so debug install and release validation are distinct pipeline stages.

Emulator and Managed Device Notes

For instrumented tests, using test-only packages can be expected. In those paths, keep install commands and Gradle tasks aligned with testing intent.

For managed devices, prefer deterministic setup scripts that include:

• uninstall previous package
• install base app
• install test package if needed
• run tests

This reduces flaky build behavior.

Preventing Test-Only Leakage to Release

Add guardrails in CI:

1. fail release job if testOnly=true
2. validate signing and variant name
3. validate versioning and package id
4. publish only approved artifact directories

These checks are lightweight and prevent costly production incidents.

Common Pitfalls

A common pitfall is always using plain adb install while working with debug APKs that require -t. Another is copying debug artifact paths into release scripts and forgetting to update them. Teams also often attempt manual manifest edits to remove test-only behavior, creating fragile build logic. Finally, skipping metadata validation in CI allows wrong APK type to pass through multiple environments before failure appears.

Summary

• INSTALL_FAILED_TEST_ONLY indicates installer blocked a test-only package.
• Use adb install -t for local debug and test workflows.
• Generate release artifacts for normal install paths.
• Validate APK metadata and variant type in CI.
• Treat test-only safeguards as protective controls, not obstacles.