android_instrumentation_test

Android instrumentation test target.

Description

Installs an Android application package under test and an Android application package that contains instrumentation tests, then runs am instrument on a connected device or emulator through Once's generic test capability.

The test package is modeled as an android_binary target whose instruments attribute points at the app under test. The android_instrumentation_test target depends on both Android application package targets. Once installs both packages with the Android Debug Bridge (adb), runs instrumentation, parses standard instrumentation status output, and writes once.test_results.v1.

Attributes

Attribute	Type	Required	Default	Description
test_app	target	no	inferred	Optional test package target used when more than one dep sets instruments
android_sdk	string	no	env	Android Software Development Kit root, otherwise ANDROID_HOME or ANDROID_SDK_ROOT
adb	string	no	Software Development Kit platform-tools	Override Android Debug Bridge path
adb_serial	string	no		Optional Android Debug Bridge device serial
javac	string	no	host tool	Override javac path used to compile the host result parser
java	string	no	host tool	Override java runtime path used by the host result parser
java_home	string	no	env	Override JAVA_HOME passed to host Java tools
instrumentation_runner	string	no	androidx.test.runner.AndroidJUnitRunner	Instrumentation runner class or component passed to am instrument
instrumentation_args	map<string,string>	no	{}	Extra am instrument -e arguments
test_class	string	no		Optional class or class#method filter lowered to -e class
clear_package_data	bool	no	false	Clear target and test package data before running instrumentation
disable_animations	bool	no	false	Set Android global animation scales to zero before running instrumentation
env	map<string,string>	no	{}	Bazel-compatible environment variables passed to the host instrumentation runner before test_env overrides
env_inherit	list<string>	no	[]	Host environment variable names inherited by the host instrumentation runner before explicit test environment values
test_env	map<string,string>	no	{}	Environment variables passed to the host instrumentation runner
args	list<string>	no	[]	Raw arguments appended to the Android instrumentation command before its component
support_apks	list<string>	no	[]	Package-relative application package globs installed before the instrumentation application
target_device	string	no	empty	Reserved device target selection
labels	list<string>	no	[]	Labels exposed through once_test_info for test discovery
timeout_ms	int	no		Optional test timeout in milliseconds

A non-empty target_device fails validation because Once does not provide the matching device provisioning behavior. Use adb_serial to select an already provisioned device.

Dependency Edges

Edge	Accepts	Description
deps	android_apk	The app under test and an android_binary test package whose instruments attribute points at that app

Providers

The target emits android_instrumentation_test and once_test_info.

Capabilities

Capability	Output groups
test	default, test_results, logs

Outputs

Output	Location
Test results	.once/out/<target>/test/test_results.json
Test log	.once/out/<target>/test/android-instrumentation-test.log
Native runner output	.once/out/<target>/test/native_results.txt

Behavior

The action is not cacheable because it depends on external device state. Once waits for a device, installs the app under test, installs the test package, optionally clears package data, and optionally disables animations. Files matched by support_apks are installed after the app under test and before the test package. Once then runs:

adb shell am instrument -w -r <args> <test-package>/<runner>

instrumentation_args entries become repeated -e key value arguments. test_class becomes -e class <value>.

Example

[[target]]
name = "GreetingApp"
kind = "android_binary"
srcs = ["src/main/**/*.kt"]

[target.attrs]
application_id = "dev.once.greeting"
manifest = "AndroidManifest.xml"
resource_files = []

[[target]]
name = "GreetingInstrumentationApk"
kind = "android_binary"
srcs = ["src/androidTest/**/*.kt"]

[target.attrs]
application_id = "dev.once.greeting.test"
manifest = "AndroidTestManifest.xml"
resource_files = []
instruments = "./GreetingApp"

[[target]]
name = "GreetingInstrumentationTests"
kind = "android_instrumentation_test"
deps = ["./GreetingApp", "./GreetingInstrumentationApk"]

[target.attrs]
test_app = "./GreetingInstrumentationApk"
labels = ["device"]