auto_screenshot: A Dart repository from isaaclyman

auto_screenshot grabs screenshots from your Flutter app on mobile platforms (iOS and Android). It's a good choice for your app if all the pages you want to screenshot are accessible by deep-link with no user interaction required.

Seed data is supported if you use a sqlite database.

Getting started

You'll need to have the following installed, with the indicated binaries available in your PATH:

xcode (only available on MacOS) - xcrun
Simulator (comes bundled with xcode)
Android SDK Command-Line Tools - emulator, adb
Java - java

To install, add auto_screenshot to your dev_dependencies in pubspec.yaml. (Run flutter pub get if your IDE doesn't do it for you.)

Set up your configuration (see below). Run flutter run targeting an iOS simulator to generate the necessary iOS app file, then run flutter build apk to build the Android APK.

The first time you run auto_screenshot on a target, you'll need to supervise it. The target will ask you for permission to open a deep link in your app. You'll need to click OK.

Commands

dart run auto_screenshot: Starts booting up simulators, loading deep links, and collecting screenshots. Make sure you've built an ipa and an appbundle for your app. auto_screenshot will look for them in the standard output folders.
dart run auto_screenshot:list_devices: Lists all the valid device names you can use in the auto_screenshot configuration.
dart run auto_screenshot:validate: Validates your auto_screenshot configuration without running any tests.

Configuration

Add a section like the following to your pubspec.yaml:

auto_screenshot:
  bundle_id: 
    android: com.example.myapp
    ios: com.example.myapp
  devices:
    - iPhone 8 Plus
    - iPhone 13 Pro Max
    - iPad Pro (12.9-inch) (2nd generation)
    - iPad Pro (12.9-inch) (5th generation)
    - Pixel_3a_API_33_arm64-v8a
    - Pixel_5_API_33
  base_url:
    android: http://flutterbooksample.com
    ios: customschema://flutterbooksample.com
  screenshot:
    - home
    - projects
    - projects/1
    - about
    - about/demo

If you want screenshots to be written to <project root>/auto_screenshot, that's all the configuration you need. Make sure to run flutter build appbundle and flutter run targeting an iOS Simulator before you run the package. This will make sure the necessary files are present.

All configuration fields:

bundle_id - (required) your app's bundle ID, like com.{domain}.{appname}. android and iOS fields are required. This should match the bundle ID your app compiles to for both iOS and Android.
devices - (required) an array of device names. These must be exact and not contain any typos. You can get a list of valid device names by running dart run auto_screenshot:list_devices. This assumes you've already installed/created the simulators you want to use, though they shouldn't be running while you're using auto_screenshot.
baseUrl - (required) the base URL for your deep links. android and iOS fields are required. Your app must be configured for deep linking; see https://docs.flutter.dev/development/ui/navigation/deep-linking.
screenshot - (required) the relative URL of each page you want to screenshot.
output_folder - (optional) path from the project root to the desired screenshot output folder. Defaults to auto_screenshot.
sqlite_folder - (optional) path from the project root to a folder containing any sqlite files you want to be placed in the data directory for your app on each simulator. If you use sqflite, for example, you can seed a .db file.

Usage

No public APIs are exported. Set up your configuration and run the exported binaries on the command line.

Support

Issues are welcome. Please don't ask to increase the scope of this project. auto_screenshot is meant to run on MacOS and capture screenshots from iPhone and Android emulators (not physical devices). It does not place the results in a frame, add text or background images, or upload assets to any app store.

FAQ

Why doesn't this use Flutter's integration testing system to allow for automated interaction?

Flutter's integration_test package is, unfortunately, in a state of neglect as far as screenshots are concerned. For screenshots to work on both platforms you have to modify your Flutter installation's objective-c code by hand, and even once it's working there are issues: device trim and cutouts aren't captured, you can only take one screenshot per test on Android, and some of the commands you're supposed to call are not available to the user in public APIs.

Development

Build autogenerated JSON maps:

dart run build_runner build

Acknowledgments

Heavily inspired by flutter_launcher_icons.

isaaclyman/auto_screenshot