Merge pull request #4 from mmcc007/dev

Added support for multiple locales and additional screens for devices

.gitignore

@@ -18,3 +18,7 @@ build/
 
 # Directory created by dartdoc
 doc/api/
+
+# screenshots
+example/ios/fastlane
+example/android/fastlane

.travis.yml

@@ -0,0 +1,68 @@
+language: generic
+os: osx
+
+jobs:
+  include:
+    - stage: Run screenshots
+#      env: Create screenshots
+      before_install:
+      # create repository for artifacts and clear if cached
+      - rm -rf $HOME/screenshots
+      - mkdir $HOME/screenshots
+
+      # install environment for flutter and simulators
+      - export HOMEBREW_NO_AUTO_UPDATE=1
+      - brew install libimobiledevice
+      - brew install ideviceinstaller
+      - brew install ios-deploy
+      - brew install cocoapods || echo 'ignore exit(1)'
+      - brew link --overwrite cocoapods
+
+      # install pre-compiled flutter
+      - FLUTTER_CHANNEL=stable
+      - FLUTTER_VERSION=1.0.0-${FLUTTER_CHANNEL}
+      - wget --quiet --output-document=flutter.zip https://storage.googleapis.com/flutter_infra/releases/${FLUTTER_CHANNEL}/macos/flutter_macos_v${FLUTTER_VERSION}.zip && unzip -qq flutter.zip > /dev/null && rm flutter.zip
+      - export PATH="$PATH":"$HOME/.pub-cache/bin"
+      - export PATH=$PWD/flutter/bin:$PWD/flutter/bin/cache/dart-sdk/bin:$PATH
+      - flutter doctor -v
+
+      # install ImageMagick
+      - brew install imagemagick
+      - pub global activate --source path .
+      script:
+      - cd example; screenshots
+      # copy artifacts to cache for later deploy
+      - tar cvzf $HOME/screenshots/screenshots.tar.gz ios/fastlane/screenshots
+      - zip -r $HOME/screenshots/screenshots.zip ios/fastlane/screenshots
+      # save artifacts for later deploy of second artifact
+      cache:
+        directories:
+          - $HOME/screenshots
+
+      # deploy draft of first artifact
+      deploy:
+        provider: releases
+        draft: true
+        skip_cleanup: true
+        api_key:
+          secure: wyPNNbjTFChWOGc/JiTpGhN490dRzz/qhU2T3CddZALjy4VN3LywennK3xnTOAq+FEYE9H/quP/SxkUX154al/lxeL6QuN5D0Ev2bL3lS9jyaoe0NOKx5GnNTzfv84taZPi768UF4rgYqzzdF8WJTCe0dlvDH7qKgH+dHIZGoB1dM/hhWMEXUv0uAZuFDkepxWHOLHsIABunkz428MEsSRCTdEWOsgdFiEl+DOC5ErmorgHazUWPpSwenz13kCLhU+wT2Fsek5tGBO6GT1Mvw8qrht3LUZBaBQJfx4yhdXQKtq0Dr+gI9a3sbF/3TKV0nRvDVA+KGmMLHT+fkRrz1xkGvrLnCDfkylDZlmn/IoQUkv4JwI+lJIXfUp40pMmSlFH1WKToWSjMsPSxv02fVYzxNZoxlno+qyKk4lfdROOSSYS5LjmMd+Lrvhmx7vNMCHl57fdXdKwgyJllxT/khMZTJv5IPQih1yi3m/hDw0s59IHYd22QHFoodcdAPy2xxeVh8VhzhucpesWAvoFZfgdTmPZXAzpMR4kEaeBb5f3Z/Eg3AypDPXg67kXwFqTRL+ZqDzOFynZYJML8RbsZd/nqU5TYc0Ocmh0YMA3v0Z43wuZMshXOXujl8z3zmnwzV/QmFP0U/phOGa9SmvKtRyGQoTGtIXoPWdXrRpgm3F4=
+        file: $HOME/screenshots/screenshots.tar.gz
+        on:
+          tags: true
+
+    - stage: Publish screenshots
+#      env: Publish screenshots to GitHub
+      # get artifacts from previous screenshots run
+      cache:
+        directories:
+          - $HOME/screenshots
+      # deploy second artifact (and mark both artifacts as published)
+      deploy:
+        provider: releases
+        draft: false
+        skip_cleanup: true
+        api_key:
+          secure: wyPNNbjTFChWOGc/JiTpGhN490dRzz/qhU2T3CddZALjy4VN3LywennK3xnTOAq+FEYE9H/quP/SxkUX154al/lxeL6QuN5D0Ev2bL3lS9jyaoe0NOKx5GnNTzfv84taZPi768UF4rgYqzzdF8WJTCe0dlvDH7qKgH+dHIZGoB1dM/hhWMEXUv0uAZuFDkepxWHOLHsIABunkz428MEsSRCTdEWOsgdFiEl+DOC5ErmorgHazUWPpSwenz13kCLhU+wT2Fsek5tGBO6GT1Mvw8qrht3LUZBaBQJfx4yhdXQKtq0Dr+gI9a3sbF/3TKV0nRvDVA+KGmMLHT+fkRrz1xkGvrLnCDfkylDZlmn/IoQUkv4JwI+lJIXfUp40pMmSlFH1WKToWSjMsPSxv02fVYzxNZoxlno+qyKk4lfdROOSSYS5LjmMd+Lrvhmx7vNMCHl57fdXdKwgyJllxT/khMZTJv5IPQih1yi3m/hDw0s59IHYd22QHFoodcdAPy2xxeVh8VhzhucpesWAvoFZfgdTmPZXAzpMR4kEaeBb5f3Z/Eg3AypDPXg67kXwFqTRL+ZqDzOFynZYJML8RbsZd/nqU5TYc0Ocmh0YMA3v0Z43wuZMshXOXujl8z3zmnwzV/QmFP0U/phOGa9SmvKtRyGQoTGtIXoPWdXrRpgm3F4=
+        file: $HOME/screenshots/screenshots.zip
+        on:
+          tags: true

README.md

@@ -1,20 +1,30 @@
 
-[![pub package](https://img.shields.io/pub/v/screenshots.svg)](https://pub.dartlang.org/packages/screenshots)
+[![pub package](https://img.shields.io/pub/v/screenshots.svg)](https://pub.dartlang.org/packages/screenshots) 
+[![Build Status](https://travis-ci.com/mmcc007/screenshots.svg?branch=master)](https://travis-ci.com/mmcc007/screenshots)
 
-![alt text][fade]
+![alt text][demo]
 
-[fade]: https://github.com/mmcc007/screenshots/raw/master/fade.gif "Screenshot with overlayed status bar and appended navigation bar placed in frame"  
-Screenshot with overlayed status bar and appended navigation bar placed in frame  
+[demo]: https://i.imgur.com/gkIEQ5y.gif "Screenshot with overlayed 
+status bar and appended navigation bar placed in frame"  
+Screenshot with overlaid status bar and appended navigation bar placed in a device frame.  
 
-For an example of screenshots generated with `screenshots` on a live app see:
-<a href="https://play.google.com/store/apps/details?id=com.orbsoft.todo"><img src="https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png" width="40%" title="GitErDone" alt="GitErDone"></a>  
+For an example of images generated with `screenshots` on a live app see:  
+<a href="https://play.google.com/store/apps/details?id=com.orbsoft.todo"><img src="https://play.google.com/intl/en_us/badges/images/generic/en_badge_web_generic.png" width="40%" title="GitErDone" alt="GitErDone"></a>
 
-For information on automating `screenshots` with a CI/CD tool see [fledge](https://github.com/mmcc007/fledge).
+Demo of `screenshots` in action:
+[![screenshots demo](https://i.imgur.com/V9VFSYb.png)](https://vimeo.com/317112577 "Screenshots demo - Click to Watch!")
+
+For introduction to `screenshots` see [article](https://medium.com/@nocnoc/automated-screenshots-for-flutter-f78be70cd5fd).
+
+For information on automating `screenshots` with a CI/CD tool see 
+[fledge](https://github.com/mmcc007/fledge).
 
 # Screenshots
 
-`screenshots` is a standalone command line utility and package for capturing screenshots for Flutter. It will start the required android emulators and iOS simulators, run your screen 
-capture tests, process the images, and drop them off for Fastlane for delivery to both stores.
+`screenshots` is a standalone command line utility and package for capturing screenshots for 
+Flutter. It will start the required android emulators and iOS simulators, run your screen 
+capture tests on each emulator/simulator for each locale your app supports, process the images, and drop them off for Fastlane 
+for delivery to both stores.
 
 It is inspired by three products from Fastlane:  
 1. [Snapshots](https://docs.fastlane.tools/getting-started/ios/screenshots/)  
@@ -25,15 +35,13 @@ It is inspired by three products from Fastlane:
    This is used to place captured iOS screenshots in a device frame.
 
 `screenshots` combines key features of all three Fastlane products.  
-1. Captures screenshots from any iOS or android device.
+1. Captures screenshots from any iOS simulator or android emulator and processes images.
 2. Frames screenshots in an iOS or android device frame.
-3. The same Flutter integration test can be used across all devices.  
+3. The same Flutter integration test can be used across all simulators/emulators.  
    No need to use iOS UI Tests or Espresso.
 4. Integrates with Fastlane's [deliver](https://docs.fastlane.tools/actions/deliver/) 
 and [supply](https://docs.fastlane.tools/actions/supply/) for upload to respective stores.
 
-See related [article](https://medium.com/@nocnoc/automated-screenshots-for-flutter-f78be70cd5fd) for more information.
-
 # Usage
 
 ````
@@ -44,14 +52,15 @@ Or, if using a config file other than the default 'screenshots.yaml':
 $ screenshots -c <path to config file>
 ````
 
-# Writing tests for `screenshots`
-Taking screenshots using this package is straightforward.
+# Modifying tests for `screenshots`
+Capturing screenshots using this package is straightforward.
 
 A special function is provided in
-the `screenshots` package that is called by the test each time you want to take a screenshot. `screenshots` will
+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 take screenshots in your tests:
+To capture screenshots in your tests:
 1. Include the `screenshots` package in your pubspec.yaml's dev_dependencies section  
    ````yaml
      screenshots: ^0.1.2
@@ -71,10 +80,23 @@ To take screenshots in your tests:
        ````dart
            await screenshot(driver, config, 'myscreenshot1');
        ````
-       Note: make sure your screenshot names are unique across all your tests.
+       
+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:
+````dart
+  WidgetsApp.debugAllowBannerOverride = false; // remove debug banner for screenshots
+````
+
+# `screenshots` on Travis
+To view `screenshots` running with the 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/
 
 # Configuration
-`screenshots` depends on a configuration file, `screenshots.yaml`:
+To run `screenshots` you need to setup a configuration file, `screenshots.yaml`:
 ````yaml
 # Screen capture tests
 tests:
@@ -84,16 +106,16 @@ tests:
 # Interim location of screenshots from tests
 staging: /tmp/screenshots
 
-# A list of locales supported in the app
+# A list of locales supported by the app
 locales:
+  - de-DE
   - en-US
-#  - de-DE
 
 # A list of devices to emulate
 devices:
   ios:
-#    - iPhone X
-    - iPhone 7 Plus
+    - iPhone X
+#    - iPhone 7 Plus
     - iPad Pro (12.9-inch) (2nd generation)
 #   "iPhone 6",
 #   "iPhone 6 Plus",
@@ -102,37 +124,91 @@ devices:
 #   "iPad Retina",
 #   "iPad Pro"
   android:
-    - Nexus 5X
+    - Nexus 6P
+#    - Nexus 5X
 
 # Frame screenshots
 frame: true
 ````
+Note: emulators and simulators corresponding to the devices in your config file must be installed
+on your test machine.
+
+## Changing configuration
+If you want to change the list of devices to run, to get different screenshots, make sure the devices
+you select have supported screens and corresponding emulators/simulators.
+
+Within each class of ios and android device, multiple devices share the same screen size.
+Devices are therefore organized by supported screens in a file called `screens.yaml`.
+
+To modify the config file with the devices you select to emulate/simulate:
+1. Locate each selected device in latest 
+[screens.yaml](https://github.com/mmcc007/screenshots/blob/master/lib/resources/screens.yaml).  
+Use the latest `screens.yaml`, not the sample below.
+2. Modify the list of devices in `screenshots.yaml` to your selected devices.  
+Confirm that each selected device name matches a name used in `screens.yaml` 
+3. Install an emulator/simulator for each selected device.  
+Confirm that each selected device used in `screenshots.yaml` has an emulator/simulator
+with a matching name.  
+
+
+`screenshots` will validate the config file before running.
 
-# Emulators and Simulators
-`screenshots` automatically starts the emulators and simulators corresponding to devices
-in the `screenshots.yaml`, on which
-you want to run your tests.  
-
-`screenshots` expects that the emulators and simulators corresponding 
-to the devices in the configuration file are installed in the test machine.
+Sample screens.yaml:
+````yaml
+ios:
+  5.5inch:
+    size: 1242x2208
+    resize: 75%
+    resources:
+      statusbar: resources/ios/1242/statusbar_black.png
+      frame: resources/ios/phones/iPhone_7_Plus_Silver.png
+    offset: -0-0
+    devices:
+      - iPhone 7 Plus
+  12.9inch:
+    size: 2048x2732
+    resize: 75%
+    resources:
+      frame: resources/ios/phones/iPad_Pro_Silver.png
+    offset: -0-0
+    devices:
+      - iPad Pro (12.9-inch) (2nd generation)
+android:
+  5.2inch:
+    size: 1080x1920
+    resize: 80%
+    resources:
+      statusbar: resources/android/1080/statusbar.png
+      navbar: resources/android/1080/navbar.png
+      frame: resources/android/phones/Nexus_5X.png
+     offset: -4-9
+    devices:
+      - Nexus 5X
+    destName: phone
+````
+If you want to use a device that is not included in screens.yaml
+, please create an [issue](https://github.com/mmcc007/screenshots/issues). Include
+the name of the device and preferably the size of the screen in pixels 
+(for example, Nexus 5X:1080x1920).
 
 # Installation
 To install `screenshots` on the command line:
 ````bash
-pub global activate screenshots
+$ pub global activate screenshots
 ````
 To upgrade, simply re-issue the command
 ````bash
-pub global activate screenshots
+$ pub global activate screenshots
 ````
-Note: the `screenshots` version should be the same for both the command line and package.  
-1. If upgrading the command line version of `screenshots`, it is helpful to also upgrade the version of `screenshots` in your pubspec.yaml.    
+Note: the `screenshots` version should be the same for both the command line and package:
+1. If upgrading the command line version of `screenshots`, it is helpful to also upgrade
+ the version of `screenshots` in your pubspec.yaml.    
 2. If upgrading `screenshots` in your pubspec.yaml, you should also upgrade the command line version.    
 
 ## Dependencies
 `screenshots` depends on ImageMagick.  
 
-Since screenshots are generally required for both iOS and Android, testing should be done on a Mac
+Since screenshots are required by both Apple and Google stores, testing should be done on a Mac
 (unless you are only testing for android).
 
 ````bash
@@ -143,59 +219,16 @@ brew update && brew install imagemagick
 Since `screenshots` is intended to be used with Fastlane, after `screenshots` completes, 
 the images can be found in:
 ````
-android/fastlane/metadata/android/en-US/images
-ios/fastlane/screenshots/en-US
+android/fastlane/metadata/android
+ios/fastlane/screenshots
 ````
 Images are in a format suitable for upload via [deliver](https://docs.fastlane.tools/actions/deliver/) 
-and [supply](https://docs.fastlane.tools/actions/supply/)
-
-If you intend to use fastlane it is better to install fastlane files in both `ios` and `android` prior to running `screenshots`.  See [fledge](https://github.com/mmcc007/fledge) for more info.
+and [supply](https://docs.fastlane.tools/actions/supply/).
 
-# Resources
-A minimum number of screen sizes are supported to meet the requirements of both stores.
-The supported screen sizes currently supported, with the corresponding devices, can be
- found in [devices.yaml](https://github.com/mmcc007/screenshots/blob/master/lib/resources/devices.yaml). 
-
- Only supported devices can be used in your config file.  
-
- Note: This file is part of the package and is shown for information purposes
- only. It does not need to be modified. You can find the latest version in [devices.yaml](https://github.com/mmcc007/screenshots/blob/master/lib/resources/devices.yaml)
-````yaml
-  ios:
-    screen1:
-        size: 1242x2208
-        resize: 75%
-        resources:
-          statusbar: resources/ios/1242/statusbar_black.png
-          frame: resources/ios/phones/iPhone_7_Plus_Silver.png
-        offset: -0-0
-        phones:
-          - iPhone 7 Plus
-    screen2:
-        size: 2048x2732
-        resize: 75%
-        resources:
-          frame: resources/ios/phones/iPad_Pro_Silver.png
-        offset: -0-0
-        phones:
-          - iPad Pro (12.9-inch) (2nd generation)
-  android:
-    screen1:
-        size: 1080x1920
-        resize: 80%
-        resources:
-          statusbar: resources/android/1080/statusbar.png
-          navbar: resources/android/1080/navbar.png
-          frame: resources/android/phones/Nexus_5X.png
-        offset: -4-9
-        phones:
-          - Nexus 5X
-        destName: phone
-````
-# Current limitations
-* More screens can be added as necessary (the minimum required by Apple and Google stores are already provided).
-* Ipad screens currently have no status bar (waiting for artwork).
-* Locales not supported (the default is whatever locale currently set in the emulator/simulator).
+If you intend to use fastlane it is better to install fastlane files, in both `ios` and `android`
+directories, prior to running `screenshots`. 
+(See [fledge](https://github.com/mmcc007/fledge) for more info.)
 
 # Issues and Pull Requests
-This is an initial release and more features can be added. [Issues](https://github.com/mmcc007/screenshots/issues) and [pull requests](https://github.com/mmcc007/screenshots/pulls) are welcome.
+[Issues](https://github.com/mmcc007/screenshots/issues) and 
+[pull requests](https://github.com/mmcc007/screenshots/pulls) are welcome.