screenshots

a screenshot image with overlaid status bar placed in a device frame.

for an example of images generated with screens.hots on a live app in both stores see:

see a demo of screens.hots in action:

screenshots from maurice mccabe on vimeo.

screenshots

screens.hots is a standalone command line utility and package for capturing screenshot images for flutter.

screens.hots will start the required android emulators and ios simulators (or find attached devices), run your screen capture tests on each emulator/simulator (or device), process the images, and drop them off to fastlane for delivery to both stores.

it is inspired by three tools from fastlane:

1. snapshots
   this is used to capture screen.shots on ios using ios ui tests.
2. screengrab
   this captures screen.shots on android using android espresso tests.
3. frameit
   this is used to place captured ios screen.shots in a device frame.

since all three of these fastlane tools do not work with flutter, screen.shots combines key features of these fastlane tools into one tool.

features

since flutter integration testing is designed to work transparently across ios and android, capturing images using scree.nshots is easy.

features include:

1. works with your existing tests
   add a single line for each screenshot.
2. run your tests on any device
   select the devices you want to run on, using a convenient config file.
3. one run for both platforms
   screen.shots runs your tests on both ios and android in one run.
   (as opposed to making separate snapshots and screengrab runs)
4. one run for multiple locales
   if your app supports multiple locales, screen.shots will optionally set the locales listed in the config file before running each test (see limitations below).
5. one run for frames
   optionally places images in device frames in same run.
   (as opposed to making separate frameit runs… which supports ios only)
6. one run for clean status bars
   every image that screen.shots generates has a clean status bar.
   (no need to run a separate stage to clean-up status bars)
7. works with fastlane
   scree.nshots drops-off images where fastlane expects to find them. fastlane’s deliver and supply can then be used to upload to respective stores.

additional automation features:

1. screen.shots runs in the cloud.
   for live demo of scree.nshots running with the internationalized example app on macos in cloud, see below
2. scree.nshots works with any ci/cd tool.
   for live demo of uploading images, generated by scree.nshots, to both store consoles, see demo of fledge at https://github.com/mmcc007/fledge#demo

installation

on macos:

$ brew update && brew install imagemagick
$ pub global activate screenshots

note:
if pub is not found, add to path using:

export path="$path:<path to flutter installation directory>/bin/cache/dart-sdk/bin"

usage

$ screenshots

or, if using a config file other than the default ‘screen.shots.yaml’:

$ screenshots -c <path to config file>

modifying your tests for screenshots

a special function is provided in the screen.shots package that is called by the test each time you want to capture a screenshot.
scree.nshots will then process the images appropriately during a scree.nshots run.

to capture screen.shots in your tests:

1. include the scree.nshots package in your pubspec.yaml’s dev_dependencies section

     screenshots: ^<current version>
   

2. in your tests
   1. import the dependencies

      import 'package:screenshots/config.dart';
      import 'package:screenshots/capture_screen.dart';
      

   2. create the config map at start of test

           final map config = config().config;
      

   3. throughout the test make calls to capture scree.nshots

          await screenshot(driver, config, 'myscreenshot1');
      

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

configuration

screenshots uses a configuration file to configure a run.
the default config filename is screenshots.yaml:

# a list of screen capture tests
tests:
  - test_driver/main1.dart
  - test_driver/main2.dart

# note: flutter driver expects a pair of files for testing
# for example:
#   main1.dart is the test app (that calls your app)
#   main1_test.dart is the matching test that flutter driver 
#   expects to find.

# interim location of screenshots from tests
staging: /tmp/screenshots

# a list of locales supported by the app
locales:
  - de-de
  - en-us

# a map of devices to emulate
devices:
  ios:
    iphone xs max:
      frame: false
    ipad pro (12.9-inch) (3rd generation):
  android:
    nexus 6p:

# frame screenshots
frame: true

note: emulators and simulators corresponding to the devices in your config file must be installed on your test machine.

device parameters

individual devices can be configured in screenshots.yaml by specifying per device parameters. (the : at the end of the device name indicates, in yaml, that a map of parameters can optionally follow.)

parameter	values	required	description
frame	true/false	optional	controls whether screenshots generated on the device should be placed in a frame. overrides the global frame setting (see example screenshots.yaml above).

integration with fastlane

since screen.shots is intended to be used with fastlane, after scree.nshots completes, the images can be found in your project at:

android/fastlane/metadata/android
ios/fastlane/screenshots

images are in a format suitable for upload via deliver
and supply.

tip: one way to use screen.shots with fastlane is to call screens.hots before calling fastlane (or optionally call from fastlane). fastlane (for either ios or android) will then find the images in the appropriate place.

(for a live demo of using fastlane to upload screenshot images to both store consoles, see demo of fledge at https://github.com/mmcc007/fledge#demo)

changing devices

to change the devices to run your tests on, just change the list of devices in screens.hots.yaml.

make sure the devices you select have supported screens and corresponding emulators/simulators.

note: in practice, multiple devices share the same screen size.
devices are therefore organized by supported screen size in a file called screens.yaml.

for each selected device:

1. confirm device is present in screens.yaml.
2. add device to the list of devices in screens.hots.yaml.
3. install an emulator or simulator for device.

scree.nshots will check your configuration before running.

upgrading

to upgrade, simply re-issue the install command

$ pub global activate screenshots

note: the screen.shots version should be the same for both the command line and in your pubspec.yaml.

1. if upgrading the command line version of scree.nshots, also upgrade
   the version of screen.shots in your pubspec.yaml.
2. if upgrading the version of scree.nshots in your pubspec.yaml, also upgrade the command line version.

to check the version of scree.nshots currently installed:

pub global list