Capturing Screenshots And Screenrecord

Capture-on-failure pattern (JUnit4 TestWatcher)

The standard pattern: a TestRule or TestWatcher fires failed() on test failure, runs screencap + logcat -d, and pulls the artefacts to a per-test directory.

class CaptureOnFailureRule(private val outputDir: File) : TestWatcher() {
    override fun failed(e: Throwable, description: Description) {
        val testName = "${description.className}.${description.methodName}"
        val device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
        val target = File(outputDir, testName).apply { mkdirs() }

        // PNG screenshot
        device.executeShellCommand("screencap -p /sdcard/fail.png")
        device.executeShellCommand("logcat -d -v threadtime").let { log ->
            File(target, "logcat.txt").writeText(log)
        }
        // The test process can pull /sdcard/fail.png via Context.getExternalFilesDir
        // or push through TestStorageService — see ../../transfer/extracting-test-artifacts/SKILL.md.
    }
}

Host-side equivalent in a CI script (see ../../automation/scripting-adb-for-ci/SKILL.md for the full version):

set +e
./gradlew connectedDebugAndroidTest
RC=$?
set -e

if [ "$RC" -ne 0 ]; then
  mkdir -p artifacts
  adb shell screencap -p /sdcard/fail.png
  adb pull /sdcard/fail.png artifacts/fail.png
  adb logcat -d -v threadtime > artifacts/logcat.txt
  adb logcat -d -b crash      -v threadtime > artifacts/crash.txt
fi
exit $RC

This captures the device's last frame plus a logcat dump only on failure (saves CI storage on green runs). For richer per-test artefact routing, prefer the AndroidX TestStorageService API — see ../../transfer/extracting-test-artifacts/SKILL.md.

Patterns

Pattern: WRONG — screencap without -p

# WRONG
adb shell screencap /sdcard/out.png
file /sdcard/out.png      # → "data" (not a PNG)
# WRONG because: without -p, screencap writes a raw RGBA framebuffer (header + naked pixel
# bytes), not a PNG. Image viewers refuse to open it. The .png extension is misleading.

# RIGHT
adb shell screencap -p /sdcard/out.png
adb pull /sdcard/out.png ./out.png

Pattern: WRONG — adb shell screencap -p > out.png on Windows

# WRONG (on Windows / certain CI hosts)
adb shell screencap -p > out.png
# WRONG because: `adb shell` allocates a PTY and translates LF to CRLF on stdout. For
# binary streams (PNG bytes) this corrupts the file.

# RIGHT (binary-clean stdout)
adb exec-out screencap -p > out.png

Pattern: long capture exceeds 3-minute cap

# WRONG — assumes a single screenrecord can capture 10 minutes
adb shell screenrecord --time-limit 600 /sdcard/run.mp4
# WRONG because: --time-limit is capped at 180. The utility silently truncates to 180.

# RIGHT — chain
for i in 1 2 3 4; do
  adb shell screenrecord --time-limit 180 /sdcard/run-$i.mp4
done
adb pull /sdcard/run-1.mp4 ./
adb pull /sdcard/run-2.mp4 ./
adb pull /sdcard/run-3.mp4 ./
adb pull /sdcard/run-4.mp4 ./
# Concatenate with ffmpeg if needed:
# ffmpeg -f concat -i list.txt -c copy out.mp4

(Or switch to scrcpy for indefinite-duration captures.)

Pattern: bug-report overlay for QA repros

adb shell screenrecord --bugreport --time-limit 60 \
  --bit-rate 8000000 --size 720x1280 /sdcard/repro.mp4
# Each frame has a frame-info + timestamp overlay aligning with logcat -v threadtime,year,UTC.
adb pull /sdcard/repro.mp4 ./repro.mp4
adb logcat -d -v threadtime,year,UTC > repro-logcat.txt

Mandatory rules

• MUST pass -p to screencap for PNG output. Without it, the file is raw RGBA and unusable in image viewers.
• MUST prefer adb exec-out screencap -p > out.png over adb shell screencap -p > out.png for streaming captures, especially on Windows or any CI host where \n → \r\n translation may apply.
• MUST treat screenrecord --time-limit as bounded by 180 s. Anything longer requires chaining or scrcpy.
• MUST stop screenrecord with adb shell pkill -INT screenrecord (not kill -9 from the host) — SIGKILL leaves the MP4 unfinalised and unplayable.
• MUST NOT assume screenrecord captures audio — it does not (developer.android.com/tools/adb#screenrecord).
• MUST NOT use screenrecord on Wear OS — unsupported.
• PREFERRED: capture-on-failure only (not on every run). Saves CI storage and points at the failing test directly.
• PREFERRED: pair every screenrecord --bugreport with a logcat -v threadtime,year,UTC dump captured at the same time. The overlay is otherwise hard to correlate.

Verification

• file ./out.png reports PNG image data after adb shell screencap -p /sdcard/out.png && adb pull /sdcard/out.png.
• On Windows CI, screenshots stream via adb exec-out screencap -p > out.png (no \r\n corruption).
• CI captures screencap and logcat -d only when the test exit code is non-zero.
• No screenrecord --time-limit <N> with N > 180 exists in any script.
• No kill -9 on a screenrecord process — only pkill -INT screenrecord so the MP4 finalises.
• CI artefact archive contains per-test sub-directories named after Class.method.

References

• developer.android.com/tools/adb#screencap — screencap syntax, -p flag, exec-out streaming.
• developer.android.com/tools/adb#screenrecord — screenrecord syntax, flags, hard limits ("Audio is not recorded", 180 s cap, no Wear OS, no rotation mid-recording).
• developer.android.com/tools/adb#shellcommands — quoting + the exec-out vs shell distinction.
• developer.android.com/training/testing/instrumented-tests/stability — screenshot/repro hygiene in instrumented tests.
• Research note tasks/research/A2-adb-shell-commands.md — full screencap / screenrecord flag tables.
• Research note tasks/research/A3-adb-observability-automation.md — capture-on-failure CI pattern; exec-out rationale.
• Sibling skill: ../../architecture/understanding-adb-architecture/SKILL.md — server / daemon / adb shell vs adb exec-out.
• Sibling skill: ../../devices/connecting-to-devices/SKILL.md — adb get-state, multi-device targeting.
• Sibling skill: ../../devices/connecting-over-wifi/SKILL.md — adb pair for wireless capture.
• Sibling skill: ../../apps/installing-and-managing-apps/SKILL.md — installing APKs to capture against.
• Sibling skill: ../../tests/running-instrumented-tests-via-adb/SKILL.md — am instrument invocation.
• Sibling skill: ../../control/injecting-input-and-state/SKILL.md — driving gestures before capturing.
• Sibling skill: ../../observability/extracting-logs-with-logcat/SKILL.md — companion logcat capture in capture-on-failure.
• Sibling skill: ../../transfer/extracting-test-artifacts/SKILL.md — adb pull and TestStorageService.
• Sibling skill: ../../automation/scripting-adb-for-ci/SKILL.md — full CI capture-on-failure pattern.
• Cross-set: ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md — the JUnit4 TestWatcher mechanic.
• Cross-set: ../../../instrumentation/scenarios/launching-activities-with-activityscenario/SKILL.md — driving an Activity to the failing state before capture.
• Cross-set: ../../../fundamentals/strategies/applying-testing-strategies/SKILL.md — when capture-on-failure beats screenshot-every-run.