screenshots 0.2.0

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 87

pub package Build Status

alt text

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

For an example of images generated with Screenshots on a live app in both stores see:
GitErDone GitErDone

See a demo of Screenshots in action: Screenshots demo

For introduction to Screenshots see https://medium.com/@nocnoc/automated-screenshots-for-flutter-f78be70cd5fd.

Screenshots #

Screenshots is a standalone command line utility and package for capturing screenshot images for Flutter.

Screenshots 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 screenshots on iOS using iOS UI Tests.
  2. Screengrab
    This captures screenshots on android using Android Espresso tests.
  3. FrameIt
    This is used to place captured iOS screenshots in a device frame.

Since all three of these Fastlane tools do not work with Flutter, Screenshots 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 Screenshots 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
    Screenshots 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, Screenshots 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 Screenshots generates has a clean status bar.
    (no need to run a separate stage to clean-up status bars)
  7. Works with Fastlane
    Screenshots 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. Screenshots runs in the cloud.
    For live demo of Screenshots running with the internationalized example app on macOS in cloud, see below
  2. Screenshots works with any CI/CD tool.
    For live demo of uploading images, generated by Screenshots, 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 'screenshots.yaml':

$ screenshots -c <path to config file>

Modifying your tests for Screenshots

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 screenshots in your tests:

  1. Include the Screenshots 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 screenshots
          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.)

ParameterValuesRequiredDescription
frametrue/falseoptionalControls 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 Screenshots is intended to be used with Fastlane, after Screenshots 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 Screenshots with Fastlane is to call Screenshots 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 screenshots.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 screenshots.yaml.
  3. Install an emulator or simulator for device.

Screenshots will check your configuration before running.

Upgrading #

To upgrade, simply re-issue the install command

$ pub global activate screenshots

Note: the Screenshots version should be the same for both the command line and in your pubspec.yaml.

  1. If upgrading the command line version of Screenshots, also upgrade the version of Screenshots in your pubspec.yaml.
  2. If upgrading the version of Screenshots in your pubspec.yaml, also upgrade the command line version.

To check the version of Screenshots currently installed:

pub global list

Sample run on Travis #

To view Screenshots running with the internationalized example app on macOS in the cloud see:
https://travis-ci.com/mmcc007/screenshots

To view the images generated by Screenshots during run on travis see:
https://github.com/mmcc007/screenshots/releases/

  • Running Screenshots in the cloud is useful for automating the generation of your screenshots in a CI/CD environment.
  • Running Screenshots on macOS in the cloud can be used to generate your screenshots when developing on Linux and/or Windows (if not using locally attached iOS devices).

Limitations #

Due to a Flutter issue (flutter/issues/27785), running Screenshots in multiple locales has limitations.

To raise priority of this Flutter issue, so it will be fixed sooner rather than later, please give a thumbs-up on flutter/issues/27785.

Priority of this limitation in Flutter project:

Dateflutter driverinternationalizationtest
4/26/2019#1#5#7
5/25/2019#1#3#6

(This limitation is being tracked by screenshots in screenshots/issues/20).

Issues and Pull Requests #

Issues and pull requests are welcome.

Your feedback is welcome and is used to guide where development effort is focused. So feel free to create as many issues and pull requests as you want. You should expect a timely and considered response.

0.2.0 #

  • Added option to control framing at device level
    (breaking change)
  • Added screen for iPad Pro (12.9-inch) (3rd generation)

0.1.8 #

  • Added support default screen for android tablet
  • Added feature to make screenshots environment available to tests
  • Improved messaging in validator
  • Added feature to auto-select black/white color of statusbar
  • Added feature to set default background color
  • Fixed problem with selecting simulators when no default available

0.1.7 #

  • Added check for highest available android emulator for a device
  • Added check for 'adb' in PATH

0.1.6 #

  • Improved handling of iOS simulator info provided by Apple

0.1.5 #

  • Updated parser for iOS simulators to work with all Apple machines
  • Added check for no running emulators and simulators on startup
  • Added check to wait for emulator to stop

0.1.4 #

0.1.3 #

  • Added support for multiple locales and additional screens for devices

0.1.2 #

  • Added configuration validation

0.1.1 #

  • Fixed parsing of simulator info on some MacOS's

0.1.0 #

  • Cleanup and release

0.0.2 #

  • Added support for iPad screenshots

0.0.1 #

  • Initial version

example/README.md

example #

The default counter app with internationalization support.

Getting Started with screenshots.

This is an app that demonstrates screenshots.

First confirm emulators/simulators are installed for the following devices:

# A list of devices to emulate
devices:
  ios:
    - iPhone X
    - iPad Pro (12.9-inch) (2nd generation)
  android:
    - Nexus 6P

The run with:

$ screenshots

The generated screenshots can be found in:

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

See screenshots in action!

To view screenshots running with this 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/

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate screenshots

2. Use it

The package has the following executables:


$ screenshots

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  screenshots: ^0.2.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:screenshots/screenshots.dart';
  
Version Uploaded Documentation Archive
0.2.0 Jun 4, 2019 Go to the documentation of screenshots 0.2.0 Download screenshots 0.2.0 archive
0.1.8 May 22, 2019 Go to the documentation of screenshots 0.1.8 Download screenshots 0.1.8 archive
0.1.7 Apr 4, 2019 Go to the documentation of screenshots 0.1.7 Download screenshots 0.1.7 archive
0.1.6 Mar 14, 2019 Go to the documentation of screenshots 0.1.6 Download screenshots 0.1.6 archive
0.1.5 Mar 5, 2019 Go to the documentation of screenshots 0.1.5 Download screenshots 0.1.5 archive
0.1.4 Feb 21, 2019 Go to the documentation of screenshots 0.1.4 Download screenshots 0.1.4 archive
0.1.3 Feb 13, 2019 Go to the documentation of screenshots 0.1.3 Download screenshots 0.1.3 archive
0.1.2 Feb 4, 2019 Go to the documentation of screenshots 0.1.2 Download screenshots 0.1.2 archive
0.1.1 Feb 3, 2019 Go to the documentation of screenshots 0.1.1 Download screenshots 0.1.1 archive
0.1.0 Jan 26, 2019 Go to the documentation of screenshots 0.1.0 Download screenshots 0.1.0 archive

All 12 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
74
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
87
Learn more about scoring.

We analyzed this package on Jun 4, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.3.1
  • pana: 0.12.17

Platforms

Detected platforms: Flutter, other

Primary library: package:screenshots/screenshots.dart with components: io, isolate.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
args ^1.5.1 1.5.2
path ^1.6.2 1.6.2
resource ^2.1.5 2.1.5
yaml ^2.1.15 2.1.15
Transitive dependencies
charcode 1.1.2
collection 1.14.11
meta 1.1.7
source_span 1.5.5
string_scanner 1.0.4
term_glyph 1.1.0
typed_data 1.1.6
Dev dependencies
test ^1.5.1+1