android_instrumentation_apk

An android_instrumentation_apk() rule is used to generate an Android Instrumentation APK.

Details

Android's Testing Fundamentals documentation includes a diagram that shows the relationship between an "application package" and a "test package" when running a test. This rule corresponds to a test package. Note that a test package has an interesting quirk where it is compiled against an application package, but must not include the resources or Java classes of the application package. Therefore, this class takes responsibility for making sure the appropriate bits are excluded. Failing to do so will generate mysterious runtime errors when running the test.

Function Signature

def android_instrumentation_apk(
    *,
    name: str,
    default_target_platform: None | str = None,
    target_compatible_with: list[str] = [],
    compatible_with: list[str] = [],
    exec_compatible_with: list[str] = [],
    visibility: list[str] = [],
    within_view: list[str] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    _android_toolchain: str = "gh_facebook_buck2_shims_meta//:android",
    _apple_platforms: dict[str, str] = {},
    _cxx_toolchain: str = gh_facebook_buck2_shims_meta//:android-hack,
    _dex_toolchain: str = "gh_facebook_buck2_shims_meta//:dex",
    _exec_os_type: str = "prelude//os_lookup/targets:os_lookup",
    _is_building_android_binary: bool = True,
    _is_force_single_cpu: bool = False,
    _is_force_single_default_cpu: bool = False,
    _java_toolchain: str = "gh_facebook_buck2_shims_meta//:java_for_android",
    apk: str,
    contacts: list[str] = [],
    cpu_filters: list[str] = [],
    deps: list[str] = [],
    disable_pre_dex: bool = False,
    enable_bootstrap_dexes: bool = False,
    includes_vector_drawables: bool = False,
    is_self_instrumenting: bool = False,
    labels: list[str] = [],
    licenses: list[str] = [],
    manifest: None | str | (str, str) = None,
    manifest_skeleton: None | str | (str, str) = None,
    min_sdk_version: None | int = None,
    multidex_min_api: None | str = None,
    preprocess_java_classes_bash: None | str = None,
    preprocess_java_classes_cmd: None | str = None,
    preprocess_java_classes_deps: list[str] = [],
    primary_dex_patterns: list[str] = [],
    use_split_dex: None | bool = None,
) -> None

Parameters

• name: (required)

  name of the target

• default_target_platform: (defaults to: None)

  specifies the default target platform, used when no platforms are specified on the command line

• target_compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with a configuration

• compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with a configuration

• exec_compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with an execution platform

• visibility: (defaults to: [])

  a list of visibility patterns restricting what targets can depend on this one

• within_view: (defaults to: ["PUBLIC"])

  a list of visibility patterns restricting what this target can depend on

• metadata: (defaults to: {})

  a key-value map of metadata associated with this target

• tests: (defaults to: [])

  a list of targets that provide tests for this one

• modifiers: (defaults to: [])

  an array of modifiers associated with this target

• apk: (required)

  APK build target, which should be used for the instrumentation APK. Can be either an android_binary() or an apk_genrule().

• contacts: (defaults to: [])

  A list of organizational contacts for this rule. These could be individuals who you would contact in the event of a failure or other issue with the rule.

  contacts = [ 'Joe Sixpack', 'Erika Mustermann' ]

• deps: (defaults to: [])

  List of build targets whose corresponding compiled Java code, Android resources, and native libraries will be included in the APK. From the transitive closure of these dependencies, the outputs of rules of the following type will be included in the APK: * android_library()* android_resource()* cxx_library()* groovy_library()* java_library()* java_binary()* prebuilt_jar()* ndk_library()* prebuilt_native_library()

• labels: (defaults to: [])

  Set of arbitrary strings which allow you to annotate a build rule with tags that can be searched for over an entire dependency tree using buck query().

• licenses: (defaults to: [])

  Set of license files for this library. To get the list of license files for a given build rule and all of its dependencies, you can use buck query

• manifest: (defaults to: None)

  Relative path to the Android manifest for the APK. The common case is that the manifest will be in the same directory as the rule, in which case this will simply be 'AndroidManifest.xml', but it can also reference an android_manifest() rule.

  Prefer using manifest_skeleton, which performs merging automatically. Exactly one of manifest and manifest_skeleton must be set.

• manifest_skeleton: (defaults to: None)

  Relative path to the skeleton Android manifest for the APK. An android_manifest() will be created automatically to merge all manifests from libraries and resources going into the app. The common case is that the manifest will be in the same directory as the rule, in which case this will simply be 'AndroidManifest.xml'.

  Exactly one of manifest and manifest_skeleton must be set.

Examples

Here is an example of an android_instrumentation_apk() rule that tests an android_binary(), and depends on a test package.

android_library(
  name = 'test',
  srcs = glob(['test/**/*.java']),
)

android_binary(
  name = 'messenger',
  manifest = 'AndroidManifest.xml',
  keystore = '//keystores:prod',
  package_type = 'release',
  proguard_config = 'proguard.cfg',
  deps = [
    ...
  ],
)

# Building this rule will produce a file named messenger_test.apk
android_instrumentation_apk(
  name = 'messenger_test',
  manifest = 'AndroidInstrumentationManifest.xml',
  apk = ':messenger',
  deps = [
    ':test',
  ],
)