Test Android Apps

View saved version →

---
name: "android-emulator-qa"
description: "Use when validating Android feature flows in an emulator with adb-driven launch, input, UI-tree inspection, screenshots, and logcat capture."
---

# Android Emulator QA

Validate Android app flows in an emulator using adb for launch, input, UI-tree inspection, screenshots, and logs.

## When to use
- QA a feature flow in an Android emulator.
- Reproduce UI bugs by driving navigation with adb input events.
- Capture screenshots and logcat output while testing.

## Quick start
1) List emulators and pick a serial:
   - `adb devices`
2) Build and install the target variant:
   - `./gradlew :<module>:install<BuildVariant> --console=plain --quiet`
   - If unsure about task names: `./gradlew tasks --all | rg install`
3) Launch the app:
   - Resolve activity: `adb -s <serial> shell cmd package resolve-activity --brief <package>`
   - Start app: `adb -s <serial> shell am start -n <package>/<activity>`
4) Capture a screenshot for visual verification:
   - `adb -s <serial> exec-out screencap -p > /tmp/emu.png`

## adb control commands
- Tap (use UI tree-derived coordinates):
  - `adb -s <serial> shell input tap <x> <y>`
- Swipe:
  - `adb -s <serial> shell input swipe <x1> <y1> <x2> <y2>`
  - Avoid edges (start ~150-200 px from left/right) to reduce accidental back gestures.
- Text:
  - `adb -s <serial> shell input text "hello"`
- Back:
  - `adb -s <serial> shell input keyevent 4`
- UI tree dump:
  - `adb -s <serial> exec-out uiautomator dump /dev/tty`

## Coordinate picking (UI tree only)
Always compute tap coordinates from the UI tree, not screenshots.

1) Dump the UI tree to a step-specific file:
   - `adb -s <serial> exec-out uiautomator dump /dev/tty > /tmp/ui-settings.xml`
2) Find the target node and derive center coordinates (`x y`) from bounds:
   - Bounds format: `bounds="[x1,y1][x2,y2]"`
   - Helper script:
   - `python3 <path-to-skill>/scripts/ui_pick.py /tmp/ui-settings.xml "Settings"`
3) If the node is missing and there are `scrollable` elements:
   - swipe, re-dump, and re-search at least once before concluding the target is missing.
4) Tap the center:
   - `adb -s <serial> shell input tap <x> <y>`

## UI tree skeleton (helper)
Use this helper to create a compact, readable overview before inspecting full XML.

1) Dump full UI tree:
   - `adb -s <serial> exec-out uiautomator dump /dev/tty > /tmp/ui-full.xml`
2) Generate summary:
   - `python3 <path-to-skill>/scripts/ui_tree_summarize.py /tmp/ui-full.xml /tmp/ui-summary.txt`
3) Review `/tmp/ui-summary.txt` to choose likely targets, then compute exact bounds from full XML.

## Logs (logcat)
1) Clear logs:
   - `adb -s <serial> logcat -c`
2) Stream app process logs:
   - Resolve pid: `adb -s <serial> shell pidof -s <package>`
   - Stream: `adb -s <serial> logcat --pid <pid>`
3) Crash buffer only:
   - `adb -s <serial> logcat -b crash`
4) Save logs:
   - `adb -s <serial> logcat -d > /tmp/logcat.txt`

## Package shortcuts
- List installed packages:
  - `adb -s <serial> shell pm list packages`
- Filter to your namespace:
  - `adb -s <serial> shell pm list packages | rg <company_or_app_id>`
- Confirm the activity resolves before launching:
  - `adb -s <serial> shell cmd package resolve-activity --brief <package>`

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: android-performance
description: Gather and interpret Android performance evidence on an adb target using Simpleperf CPU profiles, Perfetto or Compose traces, gfxinfo frame data, dumpsys meminfo snapshots, Java heap dumps, and native allocation traces. Use when asked to profile an Android app flow, find CPU-heavy functions, diagnose jank, capture startup or frame timing evidence, compare before/after performance, explain what code is taking time, or gather memory/leak profiling artifacts.
---

# Android Performance

Use this skill to capture Android performance evidence for adb-installable apps. CPU sampling usually requires a debuggable or profileable build; frame stats, Perfetto, and logcat can still help when an app cannot be sampled. Compose with `../android-emulator-qa/SKILL.md` for device selection, build/install/launch, UI driving, screenshots, UI trees, and logcat capture.

## Core Workflow

1. Pick one focused user-visible flow.
2. Choose the trace type that matches the question.
3. Record the flow with clear start and stop boundaries.
4. Pull or copy the trace produced by that run, then generate reports from that file.
5. Interpret reports with caveats about device, build type, sample count, and profiler limits.

Avoid broad "use the app for a while" captures. They make traces hard to attribute and usually hide the functions that matter.

Use a local adb target for meaningful timing. Store outputs in a run-specific artifact folder outside the skill directory:

```bash
if [ -z "${ARTIFACT_DIR:-}" ]; then
  ARTIFACT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/codex-android-perf.XXXXXX")"
fi
mkdir -p "$ARTIFACT_DIR"
```

Do not put `ARTIFACT_DIR` under `SKILL_DIR`; the skill folder is for bundled instructions and scripts, not run artifacts.

## Choosing A Trace

- Use **Simpleperf** when the question is "what functions are taking CPU time?" or when you need a sampled profile of Kotlin, Java, native, or framework execution.
- Use **Perfetto** when the question is frame timing, startup timeline, scheduler gaps, binder work, lock contention, main-thread stalls, Compose recomposition, or why a flow felt janky.
- Use **gfxinfo framestats** for a quick manual frame/jank snapshot. Pair it with Perfetto when you need root cause.
- Use **meminfo / heap dumps** when the question is retained Java/Kotlin objects, PSS, native heap, or object counts after a focused flow.

## Simpleperf CPU Profiles

Simpleperf `--app` works best when the installed package is debuggable or profileable from shell. Preflight before recording:

```bash
SERIAL="<adb-serial>"
PACKAGE="<app package>"

adb -s "$SERIAL" shell dumpsys package "$PACKAGE" | grep -Ei 'DEBUGGABLE|profileable|isProfileable' || true
```

If the package is not debuggable/profileable and `simpleperf record --app` fails, install a debug/profileable build when possible. If that is not possible, use Perfetto or `gfxinfo` instead of treating missing CPU samples as evidence.

Start recording in one terminal or as a long-running Codex command session:

```bash
SERIAL="<adb-serial>"
PACKAGE="<app package>"
MAX_DURATION_SECONDS=60

adb -s "$SERIAL" shell rm -f /data/local/tmp/perf.data
adb -s "$SERIAL" logcat -c

adb -s "$SERIAL" shell simpleperf record \
  --app "$PACKAGE" \
  -o /data/local/tmp/perf.data \
  -e cpu-clock -f 4000 -g \
  --duration "$MAX_DURATION_SECONDS"
```

While that command is running, perform exactly one focused flow with adb input, UI automation, or `android-emulator-qa`.

Stop Simpleperf from another command and wait for the recording command to exit:

```bash
adb -s "$SERIAL" shell 'pid="$(pidof simpleperf 2>/dev/null || true)"; [ -n "$pid" ] && kill -INT $pid'
```

If that returns `Operation not permitted`, send Ctrl-C to the original `adb shell simpleperf record` command session and wait for it to exit.

Pull and report the capture:

```bash
adb -s "$SERIAL" pull /data/local/tmp/perf.data "$ARTIFACT_DIR/perf.data"
adb -s "$SERIAL" logcat -d > "$ARTIFACT_DIR/logcat.

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 3 — file references are metadata, not package contents.