Android Screenshot library

On-demand screenshots during Android integration tests

This framework uses ddmlib to capture screenshots from your device, and addresses some issues around taking screenshots with ddmlib:

• ddmlib image capture is slow, around 600ms+ per image
• if the device screen is updating, the captured image is likely to show a partially-updated framebuffer
• ddmlib is invoked on the development environment side of your setup (ie your machine executing the Maven build) - your app code can't easily take screenshots itself, but in order to get best screenshot results your device screen should not be changing when the screenshot is taken

How it works

The system is in two parts, paparazzo & celebrity. Crucially, the paparazzo only takes photos when the celebrity asks.

• paparazzo - taking the photos : your desktop development environment runs an OnDemandScreenshotService, using ddmlib to listen for log messages tagged with the special tag screenshot_request.
• celebrity - the subject being photographed : your Android device runs your integration tests as it would normally, just writing a screenshot_request log message whenever it wants a screenshot taken - the paparazzo service then obliges by capturing an image from the device.

To get the best results, your test code should pause for a second after writing the log message, so that the screenshot is of a stationary screen. That simple operation is wrapped up for convenience in the Screenshots class packaged into the android-screenshot-celebrity artifact - but you don't have to use it, if you want to write the log-and-sleeping statements yourself.

Usage (for app developers)

Your app is the celebrity here - add poseForScreenshot() calls to your Android integration tests wherever you want a screenshot taken.

See this example robotium test from the open-source Gaug.es android app by GitHub - once the build finishes, the resulting animated-gif looks like this:

You'll need to ensure that you're using a build system (ie Maven) that includes the paparazzo OnDemandScreenshotService. If you're not, there'll be no negative effect - you're just writing log messages - but no screenshots will be taken.

Build systems

The android-maven plugin will include support for android-screenshot-lib as of v3.1.2, capturing screenshots during the integration-tests step. (pull-request 104)

Not to be confused with...

android-screenshot-library hosted on Google Code. Despite the names being very similar (apologies for that) this is a different library that takes a different non-ddmlib-based approach. It requires slightly more intrusive changes to your app.