![alt text][demo]
[demo]: https://i.imgur.com/gkIEQ5y.gif "Screenshot with overlaid
status bar placed in frame"
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:
See a demo of Screenshots in action:
For introduction to Screenshots see https://medium.com/@nocnoc/automated-screenshots-for-flutter-f78be70cd5fd.
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 tests, process the captured screenshots, and drop them off to Fastlane for delivery to both stores.
Screenshots is inspired by three tools from Fastlane:
Since all three of these Fastlane tools do not work with Flutter, Screenshots combines key features of these Fastlane tools into one tool.
Since Flutter integration testing is designed to work transparently across iOS and Android, capturing images using Screenshots is easy.
Features include:
screenshots
. Additional automation features:
On macOS:
brew update && brew install imagemagick
pub global activate screenshots
On linux:
# Debian, Ubuntu or Linux Mint
sudo apt-get install imagemagick
# Fedora, CentOS or RHEL
sudo yum install ImageMagick
# OpenSUSE
sudo zypper install imagemagick
pub global activate screenshots
Note: on linux ImageMagick is often already installed.
On windows:
choco install imagemagick.app
pub global activate screenshots
Note: ImageMagick v7 or later is recommended on windows.
If pub
is not found, add to PATH using:
On macOS/Linux:
export PATH="<path to flutter installation directory>/bin/cache/dart-sdk/bin:$PATH"
On windows:
set PATH=<path to flutter installation directory>\flutter\bin\cache\dart-sdk\bin;%APPDATA%\Pub\Cache\bin;%PATH%
Note: if running on Windows or Linux, can only run android devices/emulators. To also run on macOS use a CI that supports macOS.
screenshots
Or, if using a config file other than the default 'screenshots.yaml':
screenshots -c <path to config file>
Other options:
usage: screenshots [-h] [-c <config file>] [-m <normal|recording|comparison|archive>] [-f <flavor>] [-b <true|false>] [-v]
sample usage: screenshots
-c, --config=<screenshots.yaml> Path to config file.
(defaults to "screenshots.yaml")
-m, --mode=<normal|recording|comparison|archive> If mode is recording, screenshots will be saved for later comparison.
If mode is comparison, screenshots will be compared with recorded.
If mode is archive, screenshots will be archived (and cannot be uploaded via fastlane).
[normal (default), recording, comparison, archive]
-f, --flavor=<flavor name> Flavor name.
-b, --build=<true|false> Force build and install of app for all devices.
Override settings in screenshots.yaml (if any).
[true, false]
-v, --verbose Noisy logging, including all shell commands executed.
-h, --help Display this help information.
A special function is provided in the Screenshots package that is called by the test to capture a screenshot. Screenshots will then process the images appropriately during a Screenshots run.
To capture screenshots in tests:
dev_dependencies:
screenshots: ^<current version>
import 'package:screenshots/screenshots.dart';
final config = Config();
await screenshot(driver, config, 'myscreenshot1');
Note: make sure screenshot names are unique across all tests.
Note: to turn off the debug banner, in the integration test's main(), call:
WidgetsApp.debugAllowBannerOverride = false; // remove debug banner for screenshots
Screenshots uses a configuration file to configure a run.
The default config filename is screenshots.yaml
:
# A list of screen capture tests
tests:
# Note: flutter driver expects a pair of files eg, main1.dart and main1_test.dart
- test_driver/main1.dart
- test_driver/main2.dart
# Interim location of screenshots from tests
staging: /tmp/screenshots
# A list of locales supported by the app
locales:
- en-US
- de-DE
# A map of devices to emulate
devices:
ios:
iPhone XS Max:
iPhone 11 Pro:
frame: false # no screen avail so frame must be false
iPad Pro (12.9-inch) (3rd generation):
orientation:
- Portrait # default
- LandscapeRight
android:
Nexus 6P:
SM G965F: # a real attached device (frame and orientation disabled)
# Frame screenshots
frame: true
Individual devices can be configured in screenshots.yaml
by specifying per device parameters.
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). |
orientation | Portrait | LandscapeRight | PortraitUpsideDown | LandscapeLeft | optional | Controls orientation of device during test. Disables framing resulting in a raw screenshot. Ignored for real devices. |
build | true(default)/false | optional | Builds and installs app. When set to false, can be used for pre-installed apps that need to be configured before running tests. |
frame parameter notes:
orientation parameter notes:
iPhone XS Max:
orientation:
- Portrait
- LandscapeRight
In addition to using the default flutter driver mode, tests can also be specified using flutter driver parameters. For example:
tests:
- --target=test_driver/main1.dart --driver=test_driver/main1_test1.dart
- --target=test_driver/main2.dart --driver=test_driver/main2_test1.dart
Screenshots can be used to monitor any unexpected changes to the UI by comparing the new screenshots to previously recorded screenshots. Any differences will be highlighted in a 'diff' image for review.
To use this feature:
screenshots.yaml
recording: /tmp/screenshots_record
screenshots -m recording
screenshots -m comparison
Screenshots will compare the new screenshots with the recorded screenshots and generate a 'diff' image for each screenshot that does not compare. The diff image highlights the differences in red.
To generate screenshots for local use, such as generating reports of changes to UI over time, etc... use 'archive' mode.
To enable this mode:
archive: /tmp/screenshots_archive
$ screenshots -m archive
Since Screenshots is intended to be used with Fastlane, after Screenshots completes, the images can be found in the 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)
iOS images generated by Screenshots can also be further processed using FrameIt's text and background feature.
If screen is not available, disable framing by setting frame: false
for the device.
Screenshots will check configuration before running for errors and provide a guide on how to resolve.
If device does not have a screen in screens.yaml please create an issue to request a new screen.
To submit a new screen please see related README.
In some cases it is useful to know what device, device type, screen size, screen orientation and locale the test is currently running with. To obtain this information use:
final screenshotsEnv = config.screenshotsEnv;
See https://github.com/flutter/flutter/issues/31609 for related flutter driver
issue.
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 the pubspec.yaml
.
To check the version of Screenshots currently installed:
pub global list
To view Screenshots running with the internationalized example app on macOS and linux in the cloud see:
https://travis-ci.com/mmcc007/screenshots
To view the images generated by Screenshots during a run on travis see:
https://github.com/mmcc007/screenshots/releases/
To view a similar run on windows see:
https://ci.appveyor.com/project/mmcc007/screenshots
To run integration tests on real devices in cloud:
https://github.com/mmcc007/sylph
To automate releases to both stores:
https://github.com/mmcc007/fledge
Issues and pull requests are welcome.