Open-Source Testing · linkedin

test-butler

Test Butler is a LinkedIn-developed testing framework that stabilizes Android emulator environments by disabling animations, crash dialogs, and system interruptions that cause test flakiness. It provides a library and companion APK that work together to let developers programmatically control emulator settings like WiFi, orientation, and permissions during test execution.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/linkedin/test-butler

GitHub stars

Forks

Java

Primary language

Apache-2.0

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	linkedin/test-butler
Owner	linkedin
Primary language	Java
License	Apache-2.0 — OSI-approved
Stars	1k
Forks	93
Open issues	14
Latest release	2.2.1 (2021-02-11)
Last updated	2026-01-07
Source	https://github.com/linkedin/test-butler

What test-butler is

Test Butler uses an AIDL-based client-server architecture where the library communicates with a system-signed APK running on the emulator, leveraging signature-level permissions to control global settings without adb commands. The companion app must be pre-installed on stock Android emulator images and serves as a background service intercepting system calls to suppress dialogs and manage device state.

Quickstart

Get the test-butler source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/linkedin/test-butler.git2cd test-butler3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Reducing flaky Android UI tests in CI/CD

Eliminates emulator-induced test failures by disabling animations, crash dialogs, and system sleep during Espresso test runs, improving test reliability without modifying production app code.

Simulating network and device state changes

Enables test scenarios that dynamically toggle WiFi, change device orientation, set location services modes, and adjust locale—all from test code without manual adb intervention.

Testing runtime permission flows in Android 6.0+

Allows programmatic granting of Marshmallow runtime permissions directly from test code, removing the need for adb commands and debug manifest modifications.

Implementation considerations

Requires pre-installation of the Test Butler APK on each emulator instance before test execution; automate this in CI/CD setup scripts.
Must refactor any production code using isUserAMonkey() to include a helper that returns false during instrumentation, or accept true during Test Butler runs.
Add TestButler.setup() and teardown() calls in your AndroidJUnitRunner; snapshot builds are available for pre-release testing via Sonatype.
Validate that your Android emulator images use stock Android keystore; verify APK installation succeeds before relying on Test Butler in CI.
Test any custom IActivityController implementations in your app, as Test Butler also uses this interface and conflicts may occur.

When to avoid it — and what to weigh

Non-stock Android emulator images required — Test Butler will not install on Google APIs or Google Play emulator variants; it only works with stock Android images due to system keystore signing requirements.
Production dependency on ActivityManager.isUserAMonkey() — Apps that rely on isUserAMonkey() to change behavior will see it return true during Test Butler execution, potentially causing unintended test behavior unless refactored.
Physical device testing needed — Test Butler is emulator-only; it cannot be used for on-device or real device testing scenarios.
Real-time performance or low-level system testing — Disabling animations and locking CPU frequency alters emulator behavior; not suitable for performance benchmarks or low-level system validation.

License & commercial use

Licensed under Apache License 2.0 (Apache-2.0), a permissive OSI-approved license allowing use, modification, and distribution with reasonable conditions (attribution, license copy, NOTICE file).

Apache-2.0 is a permissive license permitting commercial use of Test Butler in internal testing infrastructure without licensing restrictions. Verify internal compliance policies regarding third-party open-source use; no special licensing agreement required.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Moderate
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Test Butler uses system-level permissions and AIDL interfaces; code review for AIDL contract integrity is recommended. The companion APK is signed with the emulator's stock keystore—verify integrity of downloaded APK against Maven Central checksums. Not intended for production environments; emulator-only scope limits real-world attack surface.

Alternatives to consider

Espresso IdlingResource with custom rules

Allows synchronization with animations and system state without a companion APK; lighter weight but requires more custom test code per scenario.

Appium / UI Automator framework

Broader compatibility across emulator and physical devices, but heavier overhead and less direct emulator configuration control than Test Butler.

Manual adb commands in CI/CD scripts

Lower dependency footprint but more brittle, harder to maintain, and slower to execute than Test Butler's programmatic approach.

Software development agency

Build on test-butler with DEV.co software developers

Evaluate Test Butler for your emulator-based CI/CD pipeline. Verify stock Android image compatibility, plan APK pre-installation, and refactor any isUserAMonkey() usage before deployment.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

Airtest rack-test android-emulator-runner

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing Application Development DevOps Talk to DEV.co

test-butler FAQ

Can I use Test Butler on physical devices?

No. Test Butler is emulator-only and requires system-keystore signing and signature-level permissions only available on stock Android emulators.

Why does isUserAMonkey() return true when Test Butler is running?

Test Butler sets an IActivityController, and Android's isUserAMonkey() returns true whenever any IActivityController is active. Refactor code that depends on this method to use a custom helper instead.

Do I need to add extra permissions to my debug manifest?

No. Test Butler's companion APK is system-signed, so it holds signature-level permissions directly. Your app only needs the test-butler-library dependency in androidTestImplementation.

What emulator images are supported?

Only stock Android images. Google APIs and Google Play images will not work because they use a different keystore. Verify with 'adb root' and confirm the emulator boots before installing Test Butler APK.

Custom software development services

DEV.co is a software development agency delivering custom software development services to companies building on open source. Our software developers and web developers design, integrate, and ship production systems — spanning web development, APIs, AI, data, and cloud. If test-butler is part of your open-source testing roadmap, our team can implement, customize, migrate, and maintain it.

Ready to reduce Android test flakiness?

Evaluate Test Butler for your emulator-based CI/CD pipeline. Verify stock Android image compatibility, plan APK pre-installation, and refactor any isUserAMonkey() usage before deployment.

Talk to DEV.co Schedule a Consultation