convez.ai
PluginDevOps & InfraestruturaIntermediário
ceabarr

Plugin QA Android para Claude Code

ceabarr/claude-android-plugin

Automação de QA Android via inspeção UI estruturada e captura de evidências

Ver no GitHub
BomPluginScore · de 0 a 100

Plugin que estende Claude Code para automação de testes em emuladores Android. Captura screenshots, inspeciona árvores UI via uiautomator, localiza coordenadas de toque precisamente e coleta logs logcat — eliminando adivinhações visuais em QA.

Instalação

$npx convez-ai ceabarr/claude-android-plugin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 7 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Reproduzir bugs de UI em emuladores Android de forma reprodutível
  • Validar fluxos de aplicativos Android com navegação estruturada
  • Coletar screenshots e logs logcat como evidência para análise de falhas

Veredito

Plugin técnico bem delimitado para QA Android: automatiza inspeção de UI via XML estruturado em vez de análise visual, reduzindo flakiness. Exige setup local (adb, emulador), melhor para engenheiros Android que testam em Claude Code regularmente.

README

A tradução para o português deste README ainda está na fila.

Claude Android QA Plugin

I wanted a practical Claude Code plugin for Android emulator QA, so this is the one I made. It gives Claude a repeatable way to launch apps, inspect uiautomator XML, derive tap coordinates, capture screenshots, and collect logcat evidence without guessing from screenshots.

Requirements

  • Claude Code with plugin support
  • Android Debug Bridge: adb
  • Python 3
  • Gradle or a project-specific build command when installing an app from source
  • A running Android emulator or connected Android device

Local Installation

Until this plugin is listed in the Claude plugin directory, use it locally from GitHub.

Clone the repository:

git clone https://github.com/ceabarr/claude-android-plugin.git

Start Claude Code with the plugin directory. This loads the plugin for that Claude Code session:

claude --plugin-dir /path/to/claude-android-plugin

For example:

claude --plugin-dir ~/Projects/claude-android-plugin

On Windows PowerShell, use the folder path where you cloned the repo:

claude --plugin-dir C:\Users\you\Projects\claude-android-plugin

After Claude Code starts, check /help for the plugin command:

/claude-android-qa-plugin

To update your local copy later:

cd /path/to/claude-android-plugin
git pull

Uninstalling the Local Plugin

If you loaded the plugin with --plugin-dir, there is nothing permanent to uninstall from Claude Code. Start Claude Code without the --plugin-dir flag to stop loading it.

To remove the local copy, delete the cloned repository:

rm -rf /path/to/claude-android-plugin

On Windows PowerShell:

Remove-Item -Path C:\Users\you\Projects\claude-android-plugin -Recurse -Force

Plugin Contents

  • skills/android-emulator-qa/: contextual Android emulator QA workflow
  • skills/android-emulator-qa-command/: /claude-android-qa-plugin command entry point
  • scripts/android-qa.py: wrapper CLI for common adb QA operations
  • skills/android-emulator-qa/scripts/ui_pick.py: exact text or content-desc coordinate picker
  • skills/android-emulator-qa/scripts/ui_tree_summarize.py: compact UI tree summarizer
  • assets/android-qa-plugin.png: original plugin icon

Usage

Ask Claude to validate an Android flow, reproduce an emulator UI bug, capture Android screenshots, inspect a UI tree, or collect logcat evidence. The contextual skill should activate for those requests.

Use the command for an explicit entry point:

/claude-android-qa-plugin com.example.app
/claude-android-qa-plugin reproduce the settings screen crash

Extended Test Prompts

Use this for a broad end-to-end QA pass:

Use the Claude Android QA plugin to run a full emulator QA pass for this Android app.

Target package: com.example.app
Scenario: validate the main happy path from launch through settings and back to the home screen.

Please do the following:

1. Detect connected Android devices or emulators and choose one explicit serial.
2. If this repo has an Android Gradle project, discover the install tasks and install the debug build using the OS-appropriate Gradle wrapper command.
3. Resolve the launch activity for the package and launch the app.
4. Capture an initial screenshot and UI XML dump.
5. Summarize the UI tree and identify the visible primary navigation options.
6. Use UI XML, not screenshot guessing, to find and tap the Settings entry if present.
7. After opening Settings, capture:
   - screenshot
   - UI XML
   - compact UI summary
8. Verify that the Settings screen has at least one visible interactive control or settings row.
9. Press Back and verify the app returns to the previous/home screen.
10. Capture final screenshot and UI XML.
11. Collect logcat for the target package.
12. Return a concise QA report with:
   - device serial
   - package and resolved activity
   - build/install command used, or why install was skipped
   - each screen visited
   - screenshots and UI summary paths
   - any failed taps, missing UI targets, crashes, or logcat errors
   - final pass/fail result

Important constraints:
- Do not tap coordinates guessed from screenshots.
- Always derive tap coordinates from uiautomator XML bounds.
- If a target is missing, scroll once, dump the UI tree again, and re-check before calling it missing.
- Use the plugin wrapper commands first, and raw adb only when the wrapper does not cover the needed action.

Use this to test the explicit command entry point:

/claude-android-qa-plugin com.example.app

Run a full QA pass: install if possible, launch, capture initial screenshot and UI XML, summarize the UI, navigate to Settings using XML-derived coordinates, capture evidence, return home, collect logcat, and report pass/fail with file paths.

Use this for a reproduction-style test:

/claude-android-qa-plugin

Reproduce this Android UI issue: after launching the app, opening Settings, scrolling once, and returning with Back, the app should still show the home screen without crashing or freezing.

Use the Android QA workflow end to end:
- choose a connected emulator serial
- install the app from source if this repo supports it
- resolve and launch the package
- dump UI XML before every tap
- summarize each UI tree
- derive tap coordinates only from XML bounds
- capture screenshots at launch, Settings, after scroll, and after Back
- collect app logcat and crash buffer evidence
- finish with a concise reproduction report and note whether the bug reproduced

Wrapper Examples

Use the device serial shown by adb devices -l. The first running emulator is often listed as emulator-5554, but the plugin does not assume that value.

List devices:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/android-qa.py devices

Resolve an app activity:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/android-qa.py resolve-activity --serial <serial> --package com.example.app

Dump and summarize UI XML:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/android-qa.py dump-ui --serial <serial> --out android-qa-output/ui.xml
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/android-qa.py summarize-ui --input android-qa-output/ui.xml --out android-qa-output/ui-summary.txt

Pick tap coordinates from exact UI text or content description:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/android-qa.py pick --input android-qa-output/ui.xml --target "Settings"

Capture screenshots and logs:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/android-qa.py screenshot --serial <serial> --out android-qa-output/screen.png
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/android-qa.py logcat --serial <serial> --package com.example.app --out android-qa-output/logcat.txt

Platform Notes

  • macOS/Linux shells usually use python3; Windows PowerShell often uses py -3 or python.
  • macOS/Linux Gradle wrappers usually run as ./gradlew; Windows projects often use .\gradlew.bat.
  • ${CLAUDE_PLUGIN_ROOT} is available when Claude Code runs plugin instructions. When running commands manually, replace it with the path to this plugin.
  • The examples write to android-qa-output/ so paths work naturally on Windows, macOS, and Linux.

QA Notes

Always pick tap coordinates from UI XML, not screenshots. Screenshots are evidence; XML bounds are the source of truth for automation. If a target is missing and the current tree has scrollable nodes, scroll once, dump the tree again, and search again before concluding the target is absent.

Troubleshooting

  • adb is missing: install Android platform tools and ensure adb is on PATH.
  • No devices appear: start an emulator, then run adb devices -l.
  • Activity does not resolve: confirm the package name with adb -s <serial> shell pm list packages.
  • Log capture reports no process: launch the app first, then retry log capture.
  • Tap goes to the wrong location: dump fresh UI XML and recompute coordinates before tapping.
  • For a guided run, ask Claude Code to use /claude-android-qa-plugin <package-or-task>.
Ver o original no GitHub

Bom para

Relacionados