screenshots
a command line utility and package for capturing screenshots for flutter.
screenshot with overlaid status bar and appended navigation bar placed in a device frame.
for an example of images generated with screenshot
on a live app see:
demo of screenshots
in action:
for introduction to screenshots
see article.
for information on automating screenshots
with a ci/cd tool see
fledge.
screenshots
screenshot
is a standalone command line utility and package for capturing screenshot for
flutter. it will start the required android emulators and ios simulators, run your screen
capture tests on each emulator/simulator for each locale your app supports, process the images, and drop them off for fastlane
for delivery to both stores.
it is inspired by three products from fastlane:
- snapshots
this is used to capture screenshot on ios using ios ui tests. - screengrab
this captures screenshots on android using android espresso tests. - frameit
this is used to place captured ios screenshot in a device frame.
screenshot
combines key features of all three fastlane products.
- captures screenshot from any ios simulator or android emulator and processes images.
- frames screenshot in an ios or android device frame.
- the same flutter integration test can be used across all simulators/emulators.
no need to use ios ui tests or espresso. - integrates with fastlane’s deliver
and supply for upload to respective stores.
usage
$ screenshots
or, if using a config file other than the default ‘screenshots.yaml’:
$ screenshots -c <path to config file>
modifying tests for screenshots
capturing screenshot using this package is straightforward.
a special function is provided in
the screenshots
package that is called by the test each time you want to capture a screenshot.
screenshots
will
then process the images appropriately during a screenshots
run.
to capture screenshot in your tests:
- include the
screenshots
package in your pubspec.yaml’s dev_dependencies sectionscreenshots: ^<current version>
- in your tests
- import the dependencies
import 'package:screenshots/config.dart'; import 'package:screenshots/capture_screen.dart';
- create the config map at start of test
final map config = config().config;
- throughout the test make calls to capture screenshot
await screenshot(driver, config, 'myscreenshot1');
- import the dependencies
note: make sure your screenshot names are unique across all your tests.
note: to turn off the debug banner on your screens, in your integration test’s main(), call:
widgetsapp.debugallowbanneroverride = false; // remove debug banner for screenshots
screenshots
on travis
to view screenshots
running with the example app on travis see:
https://travis-ci.com/mmcc007/screenshots
to download the images generated by screenshots
during run on travis see:
https://github.com/mmcc007/screenshots/releases/
configuration
to run screenshots
you need to setup a configuration file, screenshots.yaml
:
# screen capture tests
tests:
- test_driver/test1.dart
- test_driver/test2.dart
# interim location of screenshots from tests
staging: /tmp/screenshots
# a list of locales supported by the app
locales:
- de-de
- en-us
# a list of devices to emulate
devices:
ios:
- iphone x
# - iphone 7 plus
- ipad pro (12.9-inch) (2nd generation)
# "iphone 6",
# "iphone 6 plus",
# "iphone 5",
# "iphone 4s",
# "ipad retina",
# "ipad pro"
android:
- nexus 6p
# - nexus 5x
# frame screenshots
frame: true
note: emulators and simulators corresponding to the devices in your config file must be installed
on your test machine.
changing configuration
if you want to change the list of devices to run, to get different screenshots, make sure the devices
you select have supported screens and corresponding emulators/simulators.
within each class of ios and android device, multiple devices share the same screen size.
devices are therefore organized by supported screens in a file called screens.yaml
.
to modify the config file with the devices you select to emulate/simulate:
- locate each selected device in latest
screens.yaml.
use the latestscreens.yaml
, not the sample below. - modify the list of devices in
screenshots.yaml
to your selected devices.
confirm that each selected device name matches a name used inscreens.yaml
- install an emulator/simulator for each selected device.
confirm that each selected device used inscreenshots.yaml
has an emulator/simulator
with a matching name.
screenshots
will validate the config file before running.
sample screens.yaml:
ios:
5.5inch:
size: 1242x2208
resize: 75%
resources:
statusbar: resources/ios/1242/statusbar_black.png
frame: resources/ios/phones/iphone_7_plus_silver.png
offset: -0-0
devices:
- iphone 7 plus
12.9inch:
size: 2048x2732
resize: 75%
resources:
frame: resources/ios/phones/ipad_pro_silver.png
offset: -0-0
devices:
- ipad pro (12.9-inch) (2nd generation)
android:
5.2inch:
size: 1080x1920
resize: 80%
resources:
statusbar: resources/android/1080/statusbar.png
navbar: resources/android/1080/navbar.png
frame: resources/android/phones/nexus_5x.png
offset: -4-9
devices:
- nexus 5x
destname: phone
if you want to use a device that is not included in screens.yaml
, please create an issue. include
the name of the device and preferably the size of the screen in pixels
(for example, nexus 5x:1080×1920).
installation
to install screenshots
on the command line:
$ pub global activate screenshots
to upgrade, simply re-issue the command
$ pub global activate screenshots
note: the screenshots
version should be the same for both the command line and package:
- if upgrading the command line version of
screenshots
, it is helpful to also upgrade
the version ofscreenshots
in your pubspec.yaml. - if upgrading
screenshots
in your pubspec.yaml, you should also upgrade the command line version.
dependencies
screenshots
depends on imagemagick.
since screenshots are required by both apple and google stores, testing should be done on a mac
(unless you are only testing for android).
brew update && brew install imagemagick
integration with fastlane
since screenshots
is intended to be used with fastlane, after screenshots
completes,
the images can be found in:
android/fastlane/metadata/android
ios/fastlane/screenshots
Comments are closed.