A screenshot image with overlaid status bar placed in a device frame.
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 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:
This is used to capture screenshots on iOS using iOS UI Tests.
This captures screenshots on android using Android Espresso tests.
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.
Since Flutter integration testing is designed to work transparently across iOS and Android, capturing images using Screenshots is easy.
- Works with your existing tests
Add a single line for each screenshot.
- Run your tests on any device
Select the devices you want to run on, using a convenient config file. Screenshots will find the devices (real or emulated) and run your tests.
- 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)
- 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.
- One run for frames
Optionally places images in device frames in same run.
(as opposed to making separate FrameIt runs... which supports iOS only)
- 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)
- 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.
- Works with FrameIt
Works with Fastlane's FrameIt text and background feature to add text, etc... to a framed screenshot generated by
- Works with any attached real devices
Use any number of real devices to capture screenshots.
Additional automation features:
- Screenshots runs in the cloud.
For live demo of Screenshots running with the internationalized example app on macOS, linux and windows in cloud, see below
- 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
brew update && brew install imagemagick pub global activate screenshots
# 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.
choco install imagemagick.app pub global activate screenshots
Note: ImageMagick v7 or later is recommended on windows.
pub is not found, add to PATH using:
export PATH="<path to flutter installation directory>/bin/cache/dart-sdk/bin:$PATH"
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.
Or, if using a config file other than the default 'screenshots.yaml':
screenshots -c <path to config file>
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.
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:
- Include the Screenshots package in your pubspec.yaml's dev_dependencies section
screenshots: ^<current version>
- In your tests
- Import the dependencies
- Create the config at start of test
final config = Config();
- Throughout the test make calls to capture screenshots
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
Modifying tests based on screenshots environment #
In some cases it is useful to know what device, device type, screen size, screen orientation and locale you are currently testing with. To obtain this information in your test use:
final screenshotsEnv = config.screenshotsEnv;
See https://github.com/flutter/flutter/issues/31609 for related
flutter driver issue.
Screenshots uses a configuration file to configure a run.
The default config filename is
# 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: frame: false iPad Pro (12.9-inch) (3rd generation): orientation: LandscapeRight android: Nexus 6P: # Frame screenshots frame: true
Device Parameters #
Individual devices can be configured in
screenshots.yaml by specifying per device parameters.
|frame||true/false||optional||Controls whether screenshots generated on the device should be placed in a frame. Overrides the global frame setting (see example |
|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:
- images generated for devices where framing is disabled may not be suitable for upload.
- set to true for devices unknown to screenshots.
orientation parameter notes:
- orientation on iOS simulators is implemented using an AppleScript script which requires granting permission on first use.
Test Options #
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
Record/Compare Mode #
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:
- Add the location of your recording directory to a
- Run a recording to capture your screenshots:
screenshots -m recording
- Run subsequent Screenshots with:
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.
screenshots -m comparison
Archive Mode #
To generate screenshots for local use, such as generating reports of changes to UI over time, etc... use 'archive' mode.
To enable this mode:
- Add the location of your archive directory to screenshots.yaml:
- Run Screenshots with:
$ screenshots -m archive
Integration with Fastlane #
Since Screenshots is intended to be used with Fastlane, after Screenshots completes, the images can be found in your project at:
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)
Fastlane FrameIt #
iOS images generated by Screenshots can also be further processed using FrameIt's text and background feature.
Changing devices #
To change the devices to run your tests on, just change the list of devices in screenshots.yaml.
Make sure each device you select has a supported screen and a
corresponding attached device or installed emulator/simulator. To bypass
the supported screen requirement use
frame: false for each related device in your
For each selected device:
- Confirm device is present in screens.yaml.
- Add device to the list of devices in screenshots.yaml.
- Confirm a real device is attached, or install an emulator/simulator for device.
If your device is not found in screens.yaml but matches a screen size in screens.yaml, please create an issue or PR to add the device to screens.yaml.
Config validation #
Screenshots will check your configuration before running for any errors and provide a guide on how to resolve.
Adding new screens #
If your device does not have a screen in screens.yaml please create an issue to request a new screen.
If you want to submit a new screen please see related README.
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
- If upgrading the command line version of Screenshots, also upgrade the version of Screenshots in your pubspec.yaml.
- 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 and Appveyor #
To view the images generated by Screenshots during a run on travis see:
To view a similar run on windows see:
- 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).
Related projects #
To run integration tests on real devices in cloud:
To automate releases to both stores:
Issues and Pull Requests #
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.
- Fixed bug with multiple tests
- Fixed test of CI env var when no CI env var defined #146
- Added support for non-default config file in test #128
- Added check for flutter path at startup #136
- Added option to by-pass waitUntilNoTransientCallbacks when taking screenshot #138 #139
- Fixed bug with finding real android devices #141
- Added support for skipping builds #142
- Reduced description length to below 180 chars
A pub.dev issue
- Relaxed intl package versioning #124
- Triggered analysis on pub.dev to fix warning on transient dependency that was resolved.
- Changed tool_mobile dependency from git to pub package
Improves pub dev score
- Added support for running on linux and windows #97 #96 #106
- Removed dependency on Yaml objects #98 #100
- Added support for driver params in config of test #101
- Added support for runtime/test contexts (from flutter tools) #104
- Added logger, platform and filesystem from flutter tools to context #105
- Added support for unknown devices (without framing) #102 #110
- Created utility to test framing when adding new screens #111
- Refactored Config to remove access to raw map #114
- Breaking change in calling screenshots in tests!!
- Refactored daemon client to remove access to raw map #115
- Added getters for adb and emulator paths #116 Included adding more components from flutter tools (AndroidSdk, Config, OperatingSystemUtils, etc...).
- Added verbose mode #109 #117
- Added support for landscape screenshots #66
- Added support for flavors #55
- Modified no-frame behavior and various improvements
- Added archive feature to collect screenshots of all runs for reporting, etc... #77 #81
- Improved detection of adb path #79
- Fixed localization issue in test #19, #20
- Improved handling of locale for emulators and real devices
- Added record/compare feature to compare screenshots with previously recorded screenshots during a run. #65
- Fixed bug with parsing ios simulator info #73
- Fixed pedantic lint errors
- Added support for running on any device (real, emulator or simulator), whether booted or not, even if there are no supported screens (this requires marking unsupported devices with 'frame: false').
- Added support for FrameIt 'text and background' feature #61
- Removed requirement that no devices/emulators be running at startup #63
- Allow screenshots to be configured with multiple locales and deliberately run into flutter driver bug (with warning) #20
- Added feature to use running emulators/simulators or boot required ones #56
- Added flutter tools daemon to manage real devices, android emulators, and manage boot state of emulators and ios simulators
- Added wait-for-event to daemon client (for use in waiting for emulator to shutdown)
- Added wait-for-locale-change using syslog
- Re-organized as library
- Changed from using positional optional params to named optional params in public API (breaking change)
- Added support for iPhone Xs and iPhone Xs Max
- Added option to control framing at device level
- Added screen for iPad Pro (12.9-inch) (3rd generation)
- 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
- Added check for highest available android emulator for a device
- Added check for 'adb' in PATH
- Improved handling of iOS simulator info provided by Apple
- 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
- Bypasses changing locales if running in only one locale
- Issues warning about running flutter driver in multiple locales
See issue: https://github.com/flutter/flutter/issues/27785 for details.
- Added support for multiple locales and additional screens for devices
- Added configuration validation
- Fixed parsing of simulator info on some MacOS's
- Cleanup and release
- Added support for iPad screenshots
- Initial version
The default counter app with internationalization support.
Getting Started with
This is an app that demonstrates
First confirm devices are attached or emulators/simulators are installed for the following devices:
# A list of devices to run tests on devices: ios: iPhone XS Max: iPad Pro (12.9-inch) (2nd generation): frame: false android: Nexus 6P:
Then run with:
The generated screenshots can be found in:
screenshots in action!
screenshots running with this example app on travis see:
To download the images generated by
screenshots during run on travis see:
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:
Use this package as a library
1. Depend on it
Add this to your package's pubspec.yaml file:
dependencies: screenshots: ^2.1.1
2. Install it
You can install packages from the command line:
$ pub get
$ 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:
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
We analyzed this package on Jan 16, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
- Dart: 2.7.0
- pana: 0.13.4
|Dart SDK||>=2.2.2 <3.0.0|