Test platform code with atest

Android Studio for Platform (ASfP) integrates with atest and Soong test modules so you can run and debug platform tests on your Linux host machine, connected device, or Cuttlefish virtual device from the IDE.

Prerequisites

• Open an ASfP project configured with your AOSP checkout and lunch target.
• For device tests, connect a physical device or launch a Cuttlefish virtual device running a matching build.

Run and debug tests

You can launch platform tests and debug sessions from several places in ASfP:

• Android.bp test targets: Open an Android.bp file and click Run in the gutter next to any test module (*_test or *_test_host):
  • Run: Available for all Soong test module types (android_test, java_test_host, cc_test, rust_test, python_test, sh_test, and android_robolectric_test).
  • Debug: Available for android_test modules (attached with the Java debugger using atest --wait-for-debugger) and C++ or Rust test modules (cc_test, cc_test_host, rust_test, and rust_test_host, launched under ASfP's built-in LLDB debugger).
• Source file gutter icons: Click Run next to a test class or @Test method in your source code to run or debug that specific test.
• Right-click context menu: Right-click a test file, class, method, or Android.bp module and select Run or Debug.
• Built-in Agent (AI in Android Studio): In the Agent tool window, the Built-in Agent can run atest targets to verify changes after editing code.
• Integrated terminal: Open View > Tool Windows > Terminal to run atest commands directly.

Smart test configuration and debugging

When you launch a test from the gutter or context menu, ASfP creates and configures a Soong Test run configuration using your Android.bp module graph.

Debug android_test Java and Kotlin targets

Click the gutter icon next to an android_test module in Android.bp, or next to a Java or Kotlin JUnit class or @Test method, and then select Debug '<TestName>'. From a source file gutter, ASfP picks the nearest enclosing android_test module whose srcs include the file and names the configuration <module>, <module>:<SimpleClass>, or <module>:<SimpleClass>#<method>.

ASfP runs atest with --wait-for-debugger, reads the target package attribute from the module's AndroidManifest.xml, waits for that process on the connected device, and attaches the Java debugger.

Debug cc_test and rust_test targets under LLDB

To debug a C++ or Rust test module (cc_test, cc_test_host, rust_test, or rust_test_host), click the Android.bp gutter icon and select Debug '<TestName>'. ASfP launches the compiled test binary under its built-in LLDB debugger instead of running it through atest.

Configure the Soong Test run configuration

Open Run > Edit Configurations and select a Soong Test configuration to customize how tests build, deploy, and launch:

• Module auto-completion and Android.bp navigation: The Module field auto-completes from indexed Soong test modules in your project. Click Go to Android.bp next to the field to jump to the module's declaration in Android.bp.
• Run on: Device or Host (including host_supported: true): ASfP evaluates the module rule and its transitive defaults chain (host_supported, device_supported, enabled, target.android.enabled, and target.host.enabled):
  • Dual-target tests (cc_test and rust_test with host_supported: true): Both Device and Host radio buttons are available (defaulting to Device). Device and Host each maintain their own independent LLDB debugger template. Switching Run on between Device and Host swaps between the remote device lldb-server configuration and the local host binary configuration while preserving customizations made on each target.
  • Single-target tests: If a C++ or Rust test only builds for one environment (such as a device-only cc_test or a host-only cc_test_host or rust_test_host), ASfP selects the supported target and disables the unsupported radio button with an explanatory tooltip: "<module> (<ruleType>) doesn't build for the host or device."
• Before launch tasks (Build Native Test Module and Deploy with atest): Every Soong Test configuration includes two Before launch tasks by default:
  • Build Native Test Module: Builds <module>-target (for Device) or <module>-host (for Host) before starting LLDB.
  • Deploy with atest: When debugging on Device, runs atest <module> --collect-tests-only --disable-teardown -it -s <serial> -- --abi <abi> so Tradefed pushes test dependencies and executes target preparers before LLDB launches the binary. Hold the pointer over the Deploy with atest chip to preview the exact atest command. For faster iteration once dependencies are already on the device, remove Deploy with atest so ASfP pushes only the test binary directly. When you select Run on: Host, ASfP automatically skips Deploy with atest.
• Modify options and Debugger (LLDB options cards): Use Modify options to add optional configuration fields:
  • Program arguments (Operating System, C++ and Rust tests only): Extra arguments passed directly to the cc_test or rust_test binary after the --gtest_filter or libtest filter when debugging.
  • atest arguments (Test): Extra flags passed to atest when running the test or when preparing a device with Deploy with atest.
  • Debugger (C++ and Rust tests only): Shown when Module is a cc_test* or rust_test* target. Toggle LLDB options cards (such as Stop on entry, Cache symbols across sessions, Load symbols on demand, or With Rust visualizers for Rust tests), click Reset to defaults to reset the active Device or Host template, or add Symbol directories, Init, Pre-run, Post-run, or Exit commands, and Launch JSON (DAP Settings) from Modify options > Debugger.

View test results

Test execution progress, pass or fail status, stack traces, and device logs appear in real time inside the Run or Debug tool window in ASfP.

Tips for testing

• Run targeted tests: Test individual methods from the editor gutter without running an entire test suite.
• Use Cuttlefish snapshots: When running device tests on Cuttlefish virtual devices, use snapshots to restore a clean device state between runs.
• Inspect Soong build logs: If a test fails to compile before running, check the Soong tool window for compiler diagnostics.