| name | run-fastmediasorter |
| description | Build, install, launch, screenshot, and drive the FastMediaSorter Android app (standard-debug) on a connected emulator/device. Use when asked to run, start, build, install, launch, screenshot, smoke-test, or drive the app on a device. |
Run FastMediaSorter (standard-debug, on-device)
FastMediaSorter is an Android app (app_v2, flavor standard, build type debug,
applicationId com.sza.fastmediasorter.debug). It is driven on a real emulator/device
via adb - there is no headless mode. The agent handle is
.claude/skills/run-fastmediasorter/smoke.ps1 (launch + screenshot + crash-scan) plus
scripts/devtest/adb.ps1 for ad-hoc interaction (launch/tap/text/key/shot/log/current).
Environment: Windows dev machine, PowerShell 7, Android SDK at %LOCALAPPDATA%\Android\Sdk
(adb is not on PATH - the scripts auto-discover it). A booted emulator or attached device
is required. Paths below are relative to the repo root.
Prerequisites
- Run the mandatory
document-registry loop before the device operation and at handoff. For routine smoke runs, query -ProductArea testing and -Trigger workflow; review returned records without editing them unless the run exposes a documentation-impacting result.
- PowerShell 7 (
pwsh), Android SDK platform-tools (adb auto-discovered), JDK/Gradle via the
repo's gradlew wrapper (invoked by the builder script - never call gradle directly).
- A booted emulator or attached device. Verify:
pwsh -NoProfile -File scripts/devtest/adb.ps1 current
- Optional, only for rich UI walks (element tree, not needed for smoke): the mobile-mcp
server (
.mcp.json + Node/npx). See /spec-test-device for the mobile-mcp scenario pattern.
Build + install
Builds the standard-debug APK and installs it on the connected device (set ANDROID_SERIAL
first when more than one device is online - the builder has no device flag):
pwsh -NoProfile -File scripts/builders/build-standard-device.ps1
Run - agent path (driver)
One command: pre-flight → launch the explicit MainActivity → screenshot to temp/scratch/ → scan the
launch window for FATAL/crash/ANR. Exit 0 = alive and rendering.
pwsh -NoProfile -File .claude/skills/run-fastmediasorter/smoke.ps1
Add -Build to build+install first, -DeviceId <id> to pin a device. Screenshot lands at
temp/scratch/<device>_<TS>.png.
Ad-hoc interaction afterwards via the project's adb swiss-army (resolve targets, don't guess
coordinates):
pwsh -NoProfile -File scripts/devtest/adb.ps1 launch
pwsh -NoProfile -File scripts/devtest/adb.ps1 shot
pwsh -NoProfile -File scripts/devtest/adb.ps1 current
pwsh -NoProfile -File scripts/devtest/adb.ps1 log -Tail 200 -Grep "FATAL|Exception"
Run - human path
Build+install as above, then launch and watch the window on the emulator:
pwsh -NoProfile -File scripts/devtest/adb.ps1 launch
Gotchas
- adb is not on PATH on this machine.
adb.ps1 / device-ready.ps1 auto-discover it at
%LOCALAPPDATA%\Android\Sdk\platform-tools\adb.exe. Calling bare adb fails.
- Fresh install lands on the onboarding screen, and tapping through it is flaky. A first-run
install shows
WelcomeActivity; launching MainActivity still routes there. Programmatic taps
on «ENABLE ALL» / «NEXT» (both mobile-mcp and raw adb input tap, at correct coordinates) did
not advance it in automation. Reliable bypass: set the completion pref while the app is
stopped, then launch lands on MainActivity:
adb=~/AppData/Local/Android/Sdk/platform-tools/adb.exe
pkg=com.sza.fastmediasorter.debug
xml='<?xml version="1.0" encoding="utf-8" standalone="yes" ?><map><boolean name="welcome_completed" value="true" /></map>'
b64=$(printf %s "$xml" | base64 -w0)
"$adb" -s emulator-5554 shell am force-stop $pkg
"$adb" -s emulator-5554 shell "run-as $pkg sh -c 'mkdir -p shared_prefs; echo $b64 | base64 -d > shared_prefs/welcome_prefs.xml'"
adb shell screencap intermittently returns an all-black PNG on this emulator after a
theme/locale change or an activity transition, even while the activity is Awake and focused.
The UI is fine - the capture caught a bad frame. Trust mobile_list_elements_on_screen (the
a11y tree) over the screenshot for verifying state; re-take the screenshot if you need a real
image.- LeakCanary launcher trap. The debug build registers LeakCanary's launcher activity, so a
plain launcher-intent launch can open LeakCanary instead of the app.
adb.ps1 launch starts
the explicit MainActivity to dodge this - prefer it over a generic launch.
- Component names need the code package, not the applicationId. The applicationId is
com.sza.fastmediasorter.debug but classes live in com.sza.fastmediasorter (no .debug).
An am start -n <pkg>/.ui... short form expands the dot against the applicationId and fails
("Activity class ... does not exist"); use the FQCN
com.sza.fastmediasorter.debug/com.sza.fastmediasorter.ui....
- Emulator NAT can't reach LAN. SMB resources on
192.168.x are unreachable from the
emulator; public SFTP/FTP endpoints are reachable. Relevant when exercising network resources.
Troubleshooting
device-ready state no-device → boot an emulator / attach a device, re-run.- state
multiple-devices → pass -DeviceId <id>.
- state
package-not-installed → run smoke.ps1 -Build, or the builder script first.
device-ready exits 0 for any determined state; smoke.ps1 passes -StrictExit to get the
legacy numeric codes (2 / 3 / 4) because it is a fail-fast harness.- Builder fails with a transient "daemon stopped" → re-run the builder (known flaky).
