Extracting Test Artifacts

What TestStorage solves

• Output files land in a TestStorageService-managed directory rather than /sdcard/ proper.
• Gradle's connectedAndroidTest automatically pulls them into app/build/outputs/connected_android_test_additional_output/.
• Per-test artefact namespacing happens through the runner, not via hand-rolled Class.method filename mangling.
• Compatible with Test Orchestrator's clearPackageData: 'true' — the storage service holds artefacts even though the test app is wiped between tests.

For non-Gradle pipelines, the storage backs onto the same FS layout, addressable as /sdcard/googletest/test_outputfiles/... for legacy compatibility.

Patterns

Pattern: WRONG — adb pull /data/data/<pkg>/... on a debuggable build

# WRONG
adb pull /data/data/com.example/databases/main.db
# adb: error: failed to stat remote object '/data/data/com.example/databases/main.db': Permission denied
# WRONG because: /data/data/<pkg>/ is owned by the app UID with mode 0700. The shell user
# cannot traverse it. run-as solves this on debuggable builds.

# RIGHT — run-as + exec-out + cat for a binary-clean grab
adb exec-out run-as com.example cat databases/main.db > main.db
file main.db                 # → "SQLite 3.x database"

Or for a directory:

adb exec-out run-as com.example tar cf - databases/ | tar xf - -C ./pulled

Pattern: WRONG — adb shell run-as <pkg> cat <binary> for binary files

# WRONG (on Windows / certain CI hosts)
adb shell run-as com.example cat databases/main.db > main.db
# WRONG because: `adb shell` allocates a PTY and translates LF to CRLF on stdout. SQLite
# headers and other binary content get corrupted. The pulled DB fails to open.

# RIGHT — exec-out is binary-clean
adb exec-out run-as com.example cat databases/main.db > main.db

Pattern: writing artefacts in-app, pulling from CI

// In production / test code
val out = File(context.getExternalFilesDir(null), "captures/${name}.png")
out.outputStream().use { it.write(bitmapBytes) }

# CI script
adb pull /sdcard/Android/data/com.example/files/captures/ ./artifacts/

This works on API 30+ without run-as because /sdcard/Android/data/<pkg>/files/ is the package's own external-private dir. Both the app and adb shell (FUSE bridge) can read it.

Pattern: fast incremental push of large test data

adb push --sync -z brotli ./fixtures/ /sdcard/fixtures/

--sync skips files with matching timestamps; -z brotli compresses the wire bytes. For a fixtures dir with hundreds of unchanged files, the second push transfers nothing.

Pattern: capture-on-failure with TestStorage

class CaptureOnFailureRule : TestWatcher() {
    override fun failed(e: Throwable, description: Description) {
        val storage = PlatformTestStorageRegistry.getInstance()
        val name = "${description.className}.${description.methodName}"
        storage.openOutputFile("captures/$name.png").use { out ->
            out.write(captureScreenshotPng())
        }
    }
}

After connectedAndroidTest, the artefact lands in app/build/outputs/connected_android_test_additional_output/<flavor><Variant>/connected/<device>/captures/<name>.png automatically.

Mandatory rules

• MUST use adb exec-out run-as <pkg> cat <path> (not adb shell run-as ...) for binary file grabs. PTY translation corrupts binary on Windows and some CI hosts.
• MUST use adb exec-out run-as <pkg> tar cf - <dir> | tar xf - for directory grabs from /data/data/<pkg>/. There is no adb pull equivalent that works through run-as.
• MUST verify the build is debuggable before scripting run-as. On a release APK, run-as exits non-zero with "Package is not debuggable".
• MUST prefer /sdcard/Android/data/<pkg>/files/ (via Context.getExternalFilesDir(null)) over arbitrary /sdcard/<dir>/ for app-written test artefacts on API 30+. The latter is gated by MediaStore for app writes.
• MUST prefer TestStorage (-e useTestStorageService true + androidx.test:services) over hand-rolled /sdcard/... paths for new test infrastructure. It namespaces per-test artefacts and integrates with Gradle's connected_android_test_additional_output/ sink.
• MUST NOT rely on adb pull -p (show progress) — it is a legacy no-op on platform-tools 30+. Use the default progress meter (or -q to silence).
• MUST NOT assume adb pull of /data/data/<pkg>/... works without run-as. It does not, even on debuggable builds — pull is a shell-user operation.
• PREFERRED: --sync -z brotli for repeated pushes of large fixture sets. Brotli + timestamp-skip is dramatically faster on slow USB 2.0 cables.
• PREFERRED: Test Orchestrator + clearPackageData: 'true' + useTestStorageService: 'true' for hermetic test isolation with retained artefacts.

Verification

• No script invokes adb pull /data/data/<pkg>/... directly. All such pulls go through run-as.
• Binary-file pulls use adb exec-out, not adb shell.
• All app-written test artefacts target Context.getExternalFilesDir(...) (lands at /sdcard/Android/data/<pkg>/files/), not /sdcard/<arbitrary>/.
• CI archives app/build/outputs/connected_android_test_additional_output/**/* for the modern artefact API.
• Repeated pushes of the same fixture dir use adb push --sync so unchanged files are skipped.
• file reports the correct binary type for every pulled artefact (no CRLF corruption).
• Release APKs have no test code paths that try to adb pull from /data/data/<pkg>/... — those would fail.

References

• developer.android.com/tools/adb — pull/push syntax, "let you copy arbitrary directories and files to any location in a device" quote.
• developer.android.com/studio/test/command-line — Gradle output dir conventions: HTML at module/build/reports/androidTests/connected/, XML at module/build/outputs/androidTest-results/connected/.
• developer.android.com/training/data-storage/app-specific — Context.getExternalFilesDir() and the API-30+ scoped-storage rules.
• developer.android.com/reference/androidx/test/services/storage/TestStorage — the modern artefact API.
• developer.android.com/reference/androidx/test/platform/io/PlatformTestStorageRegistry — host-side handle.
• Research note tasks/research/A3-adb-observability-automation.md — full pull/push surface, path permission rules, run-as patterns, scoped storage on Android 11+, TestStorage wiring.
• Sibling skill: ../../architecture/understanding-adb-architecture/SKILL.md — server / daemon, exec-out vs shell.
• Sibling skill: ../../devices/connecting-to-devices/SKILL.md — adb get-state, multi-device targeting.
• Sibling skill: ../../devices/connecting-over-wifi/SKILL.md — wireless transport.
• Sibling skill: ../../apps/installing-and-managing-apps/SKILL.md — pm install and the debuggable-build flag.
• Sibling skill: ../../tests/running-instrumented-tests-via-adb/SKILL.md — am instrument arguments including useTestStorageService.
• Sibling skill: ../../control/injecting-input-and-state/SKILL.md — driving the scenario that produces the artefact.
• Sibling skill: ../../capture/capturing-screenshots-and-screenrecord/SKILL.md — producing PNG / MP4 to pull.
• Sibling skill: ../../observability/extracting-logs-with-logcat/SKILL.md — pulling rotated log files via adb shell logcat -f + adb pull.
• Sibling skill: ../../automation/scripting-adb-for-ci/SKILL.md — full CI orchestration.
• Cross-set: ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md — TestWatcher rules wired to TestStorage.
• Cross-set: ../../../instrumentation/scenarios/launching-activities-with-activityscenario/SKILL.md — Activity-driven scenarios that emit artefacts.
• Cross-set: ../../../fundamentals/strategies/applying-testing-strategies/SKILL.md — when artefacts are the right observability layer.