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

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, 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. 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.
• 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.

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 – Transforms raw accessibility dumps into hierarchical JSON summaries suitable for LLM analysis.
• 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 – Runs simpleperf to identify CPU-intensive code paths.
• 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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	Complete argument specification and usage notes for UI testing.
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	Python utility for parsing Android UI hierarchy dumps into JSON trees.
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	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.
• 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 to process UI states, while android-performance leverages 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}