# How to Handle Android Testing with OpenAI Plugins: A Complete Guide

> Learn to automate Android testing with OpenAI plugins. This guide explains how to use the test-android-apps plugin for emulator provisioning, UI automation, and performance profiling.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-10

---

**You can automate end-to-end Android testing by invoking the `test-android-apps` plugin, which composes emulator provisioning, UI automation, and performance profiling into discrete, stateless skills accessible via JSON requests.**

The `openai/plugins` repository provides a dedicated Android testing framework that eliminates manual toolchain configuration. By registering the `android-emulator-qa` and `android-performance` skills in [`plugins/test-android-apps/plugin.lock.json`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/plugin.lock.json), the system allows large language models to boot emulators, execute functional tests, and capture CPU or memory metrics without custom infrastructure. This guide examines the source code implementation, skill composition patterns, and exact request formats required to integrate these capabilities into your testing workflows.

## Understanding the test-android-apps Plugin Architecture

The `test-android-apps` plugin encapsulates Android testing logic as **Codex-style** skills defined in the repository’s [`plugin.lock.json`](https://github.com/openai/plugins/blob/main/plugin.lock.json). Each skill represents a stateless operation that accepts YAML-encoded arguments and returns structured JSON artefacts.

### Core Skills Overview

The plugin exposes two primary capabilities:

- **`android-emulator-qa`** – Manages the full device lifecycle, including emulator startup, APK installation, UI tree extraction, screenshot capture, and logcat collection. Defined in [`plugins/test-android-apps/skills/android-emulator-qa/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/skills/android-emulator-qa/SKILL.md).
- **`android-performance`** – Attaches profilers to running emulators to generate CPU hotspots, heap dumps, and Perfetto traces. Defined in [`plugins/test-android-apps/skills/android-performance/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/skills/android-performance/SKILL.md).

Both skills create fresh temporary environments on each invocation, ensuring **stateless** execution and complete isolation between test sessions.

## How the Android Emulator QA Skill Works

The `android-emulator-qa` skill handles functional testing infrastructure. When invoked, it uses the host Android SDK to boot a named emulator, install the specified APK, and execute a user-provided test script.

### UI Processing and Helper Scripts

Under `plugins/test-android-apps/skills/android-emulator-qa/scripts/`, the skill relies on Python utilities to parse interface states:

- [`ui_tree_summarize.py`](https://github.com/openai/plugins/blob/main/ui_tree_summarize.py) – Transforms raw accessibility dumps into hierarchical JSON summaries suitable for LLM analysis.
- [`ui_pick.py`](https://github.com/openai/plugins/blob/main/ui_pick.py) – Facilitates interactive element selection during automated test runs.

The skill writes outputs to temporary directories (e.g., `${TMPDIR:-/tmp}/codex-android-qa...`), returning JSON payloads containing URLs to UI trees and screenshots captured during script execution.

## Profiling with the Android Performance Skill

Once functional testing completes, the `android-performance` skill connects to the running emulator instance to collect telemetry. This skill accepts the `device_id` returned by the emulator skill and produces machine-readable performance reports.

### Profiling Scripts and Capabilities

Located in `plugins/test-android-apps/skills/android-performance/scripts/`, the skill executes shell wrappers around platform profiling tools:

- [`simpleperf_hotspots.sh`](https://github.com/openai/plugins/blob/main/simpleperf_hotspots.sh) – Runs `simpleperf` to identify CPU-intensive code paths.
- [`heapprofd_reports.sh`](https://github.com/openai/plugins/blob/main/heapprofd_reports.sh) – Captures native heap allocation profiles.

The skill supports three profiling modes via the `profile_type` argument: `cpu`, `memory`, or `perfetto`. Results are written to `${TMPDIR:-/tmp}/codex-android-perf...` directories and returned as downloadable URLs in the JSON response.

## Architectural Flow and Skill Composition

The OpenAI plugins architecture enables automatic sequencing of dependent skills. For a complete testing workflow, the model composes the two skills linearly:

1. **Emulator Setup** – Invoke `android-emulator-qa` to create the device, install the APK, and execute UI tests.
2. **Performance Analysis** – Pass the returned `device_id` to `android-performance` to initiate profiling.

This composition pattern ensures the emulator exists before profiling begins. Each skill invocation is independent, with state passed explicitly through the `device_id` parameter and artefact URLs.

## Practical Implementation Examples

To execute Android testing, send HTTP requests to the OpenAI Plugins endpoint with `plugin_key` set to `test-android-apps`.

### Running Functional UI Tests

First, initialize the emulator and install your APK:

```json
{
  "plugin_key": "test-android-apps",
  "skill": "android-emulator-qa",
  "args": {
    "apk_path": "/path/to/app-debug.apk",
    "script_path": "/path/to/ui_test.sh",
    "emulator_name": "pixel_5_api_33"
  }
}

```

The skill returns a structured response containing the device identifier and captured artefacts:

```json
{
  "status": "ok",
  "device_id": "emulator-5554",
  "ui_trees": ["https://.../ui_tree_1.json", "https://.../ui_tree_2.json"],
  "screenshots": ["https://.../screen1.png", "https://.../screen2.png"]
}

```

### Executing Performance Profiling

Use the `device_id` from the previous response to capture performance data:

```json
{
  "plugin_key": "test-android-apps",
  "skill": "android-performance",
  "args": {
    "device_id": "emulator-5554",
    "profile_type": "cpu",
    "duration_seconds": 30
  }
}

```

The performance skill returns processed analysis:

```json
{
  "status": "ok",
  "cpu_hotspots": ["https://.../hotspots.txt"],
  "summary": "Top hot spots: com.example.myapp.MainActivity (45% CPU)"
}

```

## Key Source Files and Implementation Details

Understanding the underlying file structure enables advanced debugging and skill customization:

| File | Purpose |
|------|---------|
| [`plugins/test-android-apps/skills/android-emulator-qa/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/skills/android-emulator-qa/SKILL.md) | Complete argument specification and usage notes for UI testing. |
| [`plugins/test-android-apps/skills/android-performance/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/skills/android-performance/SKILL.md) | Configuration reference for profiling options and artefact handling. |
| [`plugins/test-android-apps/skills/android-emulator-qa/scripts/ui_tree_summarize.py`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/skills/android-emulator-qa/scripts/ui_tree_summarize.py) | Python utility for parsing Android UI hierarchy dumps into JSON trees. |
| [`plugins/test-android-apps/skills/android-performance/scripts/simpleperf_hotspots.sh`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/skills/android-performance/scripts/simpleperf_hotspots.sh) | Bash wrapper for executing `simpleperf` and extracting CPU hotspots. |
| [`plugins/test-android-apps/plugin.lock.json`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/plugin.lock.json) | Plugin registry defining skill entry points and metadata. |

## Summary

- The **`test-android-apps`** plugin provides two specialized skills—`android-emulator-qa` for functional testing and `android-performance` for profiling—registered in [`plugins/test-android-apps/plugin.lock.json`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/plugin.lock.json).
- Both skills are **stateless**, accepting YAML-encoded arguments and writing results to temporary directories with URL references returned in JSON responses.
- The **`android-emulator-qa`** skill uses helper scripts like [`ui_tree_summarize.py`](https://github.com/openai/plugins/blob/main/ui_tree_summarize.py) to process UI states, while **`android-performance`** leverages [`simpleperf_hotspots.sh`](https://github.com/openai/plugins/blob/main/simpleperf_hotspots.sh) for CPU analysis.
- Skills are **composed sequentially** using the `device_id` parameter, enabling automated pipelines that move from emulator setup to performance profiling without manual intervention.

## Frequently Asked Questions

### What is the test-android-apps plugin?

The `test-android-apps` plugin is a Codex-style plugin in the `openai/plugins` repository that exposes Android testing capabilities to language models. Registered in [`plugins/test-android-apps/plugin.lock.json`](https://github.com/openai/plugins/blob/main/plugins/test-android-apps/plugin.lock.json), it bundles the `android-emulator-qa` and `android-performance` skills, allowing automated APK installation, UI interaction capture, and system profiling through standardized JSON requests.

### How do I pass parameters to Android testing skills?

Each skill accepts a YAML-encoded `args` object within the JSON request body. For `android-emulator-qa`, required parameters include `apk_path`, `script_path`, and `emulator_name`. For `android-performance`, you must provide `device_id`, `profile_type` (set to `cpu`, `memory`, or `perfetto`), and optional fields like `duration_seconds`. Full argument schemas are documented in the respective [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files.

### Where are test artefacts stored?

Both skills write outputs to temporary directories under `${TMPDIR:-/tmp}/` using prefixed paths such as `codex-android-perf...` for performance data and `ui_trees/...` for interface captures. The JSON response includes signed URLs to these artefacts, which remain accessible for the duration of the session before automatic cleanup removes the temporary files.

### Can I run UI tests and performance profiling together?

Yes. The OpenAI plugins architecture supports automatic skill composition. The model can chain the `android-emulator-qa` skill—which returns a `device_id`—directly into the `android-performance` skill using that identifier as the `device_id` argument. This creates a seamless testing pipeline where functional validation immediately precedes performance analysis on the same emulator instance.