fastlane 2.61.0.beta.20171006010004 → 2.61.0.beta.20171007010004

data/fastlane/lib/fastlane/actions/docs/snapshot.md

@@ -0,0 +1,333 @@
+<p align="center">
+  <img src="/img/actions/snapshot.png" height="110">
+</p>
+
+###### Automate taking localized screenshots of your iOS and tvOS apps on every device
+
+<hr />
+<h4 align="center">
+  Check out the new <a href="https://docs.fastlane.tools/getting-started/ios/screenshots">fastlane documentation</a> on how to generate screenshots
+</h4>
+<hr />
+
+_snapshot_ generates localized iOS and tvOS screenshots for different device types and languages for the App Store and can be uploaded using ([_deliver_](https://github.com/fastlane/fastlane/tree/master/deliver)).
+
+You have to manually create 20 (languages) x 6 (devices) x 5 (screenshots) = **600 screenshots**.
+
+It's hard to get everything right!
+
+- New screenshots with every (design) update
+- No loading indicators
+- Same content / screens
+- [Clean Status Bar](#use-a-clean-status-bar)
+- Uploading screenshots ([_deliver_](https://github.com/fastlane/fastlane/tree/master/deliver) is your friend)
+
+More information about [creating perfect screenshots](https://krausefx.com/blog/creating-perfect-app-store-screenshots-of-your-ios-app).
+
+_snapshot_ runs completely in the background - you can do something else, while your computer takes the screenshots for you.
+
+-------
+
+<p align="center">
+    <a href="#features">Features</a> &bull;
+    <a href="#ui-tests">UI Tests</a> &bull;
+    <a href="#quick-start">Quick Start</a> &bull;
+    <a href="#usage">Usage</a> &bull;
+    <a href="#tips">Tips</a> &bull;
+    <a href="#how-does-it-work">How?</a>
+</p>
+
+-------
+
+# Features
+- Create hundreds of screenshots in multiple languages on all simulators
+- Take screenshots in multiple device simulators concurrently to cut down execution time (Xcode 9 only)
+- Configure it once, store the configuration in git
+- Do something else, while the computer takes the screenshots for you
+- Integrates with [_fastlane_](https://fastlane.tools) and [_deliver_](https://github.com/fastlane/fastlane/tree/master/deliver)
+- Generates a beautiful web page, which shows all screenshots on all devices. This is perfect to send to QA or the marketing team
+- _snapshot_ automatically waits for network requests to be finished before taking a screenshot (we don't want loading images in the App Store screenshots)
+
+After _snapshot_ successfully created new screenshots, it will generate a beautiful HTML file to get a quick overview of all screens:
+
+![img/actions/htmlPagePreviewFade.jpg](assets/htmlPagePreviewFade.jpg)
+
+## Why?
+
+This tool automatically switches the language and device type and runs UI Tests for every combination.
+
+### Why should I automate this process?
+
+- It takes **hours** to take screenshots
+- You get a great overview of all your screens, running on all available simulators without the need to manually start it hundreds of times
+- Easy verification for translators (without an iDevice) that translations do make sense in real App context
+- Easy verification that localizations fit into labels on all screen dimensions
+- It is an integration test: You can test for UI elements and other things inside your scripts
+- Be so nice, and provide new screenshots with every App Store update. Your customers deserve it
+- You realise, there is a spelling mistake in one of the screens? Well, just correct it and re-run the script
+
+# UI Tests
+
+## Getting started
+This project uses Apple's newly announced UI Tests. We will not go into detail on how to write scripts.
+
+Here a few links to get started:
+
+- [WWDC 2015 Introduction to UI Tests](https://developer.apple.com/videos/play/wwdc2015-406/)
+- [A first look into UI Tests](http://www.mokacoding.com/blog/xcode-7-ui-testing/)
+- [UI Testing in Xcode 7](http://masilotti.com/ui-testing-xcode-7/)
+- [HSTestingBackchannel : ‘Cheat’ by communicating directly with your app](https://github.com/ConfusedVorlon/HSTestingBackchannel)
+- [Automating App Store screenshots using fastlane snapshot and frameit](https://tisunov.github.io/2015/11/06/automating-app-store-screenshots-generation-with-fastlane-snapshot-and-sketch.html)
+
+# Quick Start
+
+- Create a new UI Test target in your Xcode project ([top part of this article](https://krausefx.com/blog/run-xcode-7-ui-tests-from-the-command-line))
+- Run `fastlane snapshot init` in your project folder
+- Add the ./SnapshotHelper.swift to your UI Test target (You can move the file anywhere you want)
+ - **Note:** if you're using Xcode 8, add the ./SnapshotHelperXcode8.swift to your UI Test target
+- (Objective C only) add the bridging header to your test class.
+ - `#import "MYUITests-Swift.h"`
+ - The bridging header is named after your test target with -Swift.h appended.
+- In your UI Test class, click the `Record` button on the bottom left and record your interaction
+- To take a snapshot, call the following between interactions
+ -  Swift: `snapshot("01LoginScreen")`
+ -  Objective C: `[Snapshot snapshot:@"01LoginScreen" waitForLoadingIndicator:YES];`
+- Add the following code to your `setUp()` method
+
+**Swift**
+```swift
+let app = XCUIApplication()
+setupSnapshot(app)
+app.launch()
+```
+
+**Objective C**
+```objective-c
+XCUIApplication *app = [[XCUIApplication alloc] init];
+[Snapshot setupSnapshot:app];
+[app launch];
+```
+
+_Make sure you only have one `launch` call in your test class, as Xcode adds one automatically on new test files._
+
+![img/actions/snapshot.gif](assets/snapshot.gif)
+
+You can try the _snapshot_ [example project](https://github.com/fastlane/fastlane/tree/master/snapshot/example) by cloning this repo.
+
+To quick start your UI tests, you can use the UI Test recorder. You only have to interact with the simulator, and Xcode will generate the UI Test code for you. You can find the red record button on the bottom of the screen (more information in [this blog post](https://krausefx.com/blog/run-xcode-7-ui-tests-from-the-command-line))
+
+# Usage
+
+```no-highlight
+fastlane snapshot
+```
+
+Your screenshots will be stored in the `./screenshots/` folder by default (or `./fastlane/screenshots` if you're using [fastlane](https://fastlane.tools))
+
+New with Xcode 9, *snapshot* can run multiple simulators concurrently. This is the default behavior in order to take your screenshots as quickly as possible. This can be disabled to run each device, one at a time, by setting the `:concurrent_simulators` option to `false`.
+
+**Note:** While running *snapshot* with Xcode 9, the simulators will not be visibly spawned. So, while you wont see the simulators running your tests, they will, in fact, be taking your screenshots.
+
+If any error occurs while running the snapshot script on a device, that device will not have any screenshots, and _snapshot_ will continue with the next device or language. To stop the flow after the first error, run
+
+```no-highlight
+fastlane snapshot --stop_after_first_error
+```
+
+Also by default, _snapshot_ will open the HTML after all is done. This can be skipped with the following command
+
+
+```no-highlight
+fastlane snapshot --stop_after_first_error --skip_open_summary
+```
+
+There are a lot of options available that define how to build your app, for example
+
+```no-highlight
+fastlane snapshot --scheme "UITests" --configuration "Release"  --sdk "iphonesimulator"
+```
+
+Reinstall the app before running _snapshot_
+
+```no-highlight
+fastlane snapshot --reinstall_app --app_identifier "tools.fastlane.app"
+```
+
+By default _snapshot_ automatically retries running UI Tests if they fail. This is due to randomly failing UI Tests (e.g. [#372](https://github.com/fastlane/snapshot/issues/372)). You can adapt this number using
+
+```no-highlight
+fastlane snapshot --number_of_retries 3
+```
+
+Add photos and/or videos to the simulator before running _snapshot_
+
+```no-highlight
+fastlane snapshot --add_photos MyTestApp/Assets/demo.jpg --add_videos MyTestApp/Assets/demo.mp4
+```
+
+For a list for all available options run
+
+```no-highlight
+fastlane action snapshot
+```
+
+After running _snapshot_ you will get a nice summary:
+
+<img src="/img/actions/testSummary.png" width="500">
+
+## Snapfile
+
+All of the available options can also be stored in a configuration file called the `Snapfile`. Since most values will not change often for your project, it is recommended to store them there:
+
+First make sure to have a `Snapfile` (you get it for free when running `fastlane snapshot init`)
+
+The `Snapfile` can contain all the options that are also available on `fastlane action snapshot`
+
+
+```ruby
+scheme "UITests"
+
+devices([
+  "iPhone 6",
+  "iPhone 6 Plus",
+  "iPhone 5",
+  "iPhone 4s"
+])
+
+languages([
+  "en-US",
+  "de-DE",
+  "es-ES",
+  ["pt", "pt_BR"] # Portuguese with Brazilian locale
+])
+
+launch_arguments(["-username Felix"])
+
+# The directory in which the screenshots should be stored
+output_directory './screenshots'
+
+clear_previous_screenshots true
+
+add_photos ["MyTestApp/Assets/demo.jpg"]
+
+```
+
+### Completely reset all simulators
+
+You can run this command in the terminal to delete and re-create all iOS and tvOS simulators:
+
+```no-highlight
+fastlane snapshot reset_simulators
+```
+
+**Warning**: This will delete **all** your simulators and replace by new ones! This is useful, if you run into weird problems when running _snapshot_.
+
+You can use the environment variable `SNAPSHOT_FORCE_DELETE` to stop asking for confirmation before deleting.
+
+## Update snapshot helpers
+
+Some updates require the helper files to be updated. _snapshot_ will automatically warn you and tell you how to update.
+
+Basically you can run
+
+```no-highlight
+fastlane snapshot update
+```
+
+to update your `SnapshotHelper.swift` files. In case you modified your `SnapshotHelper.swift` and want to manually update the file, check out [SnapshotHelper.swift](https://github.com/fastlane/fastlane/blob/master/snapshot/lib/assets/SnapshotHelper.swift).
+
+## Launch Arguments
+
+You can provide additional arguments to your app on launch. These strings will be available in your app (eg. not in the testing target) through `ProcessInfo.processInfo.arguments`. Alternatively, use user-default syntax (`-key value`) and they will be available as key-value pairs in `UserDefaults.standard`.
+
+```ruby
+launch_arguments([
+  "-firstName Felix -lastName Krause"
+])
+```
+
+```swift
+name.text = UserDefaults.standard.string(forKey: "firstName")
+// name.text = "Felix"
+```
+
+_snapshot_ includes `-FASTLANE_SNAPSHOT YES`, which will set a temporary user default for the key `FASTLANE_SNAPSHOT`, you may use this to detect when the app is run by _snapshot_.
+
+```swift
+if UserDefaults.standard.bool(forKey: "FASTLANE_SNAPSHOT") {
+    // runtime check that we are in snapshot mode
+}
+```
+
+Specify multiple argument strings and _snapshot_ will generate screenshots for each combination of arguments, devices, and languages. This is useful for comparing the same screenshots with different feature flags, dynamic text sizes, and different data sets.
+
+```ruby
+# Snapfile for A/B Test Comparison
+launch_arguments([
+  "-secretFeatureEnabled YES",
+  "-secretFeatureEnabled NO"
+])
+```
+
+# How does it work?
+
+The easiest solution would be to just render the UIWindow into a file. That's not possible because UI Tests don't run on a main thread. So _snapshot_ uses a different approach:
+
+When you run unit tests in Xcode, the reporter generates a plist file, documenting all events that occurred during the tests ([More Information](http://michele.io/test-logs-in-xcode)). Additionally, Xcode generates screenshots before, during and after each of these events. There is no way to manually trigger a screenshot event. The screenshots and the plist files are stored in the DerivedData directory, which _snapshot_ stores in a temporary folder.
+
+When the user calls `snapshot(...)` in the UI Tests (Swift or Objective C) the script actually does a rotation to `.Unknown` which doesn't have any effect on the actual app, but is enough to trigger a screenshot. It has no effect to the application and is not something you would do in your tests. The goal was to find *some* event that a user would never trigger, so that we know it's from _snapshot_. On tvOS, there is no orientation so we ask for a count of app views with type "Browser" (which should never exist on tvOS).
+
+_snapshot_ then iterates through all test events and check where we either did this weird rotation (on iOS) or searched for browsers (on tvOS). Once _snapshot_ has all events triggered by _snapshot_ it collects a ordered list of all the file names of the actual screenshots of the application.
+
+In the test output, the Swift _snapshot_ function will print out something like this
+
+> snapshot: [some random text here]
+
+_snapshot_ finds all these entries using a regex. The number of _snapshot_ outputs in the terminal and the number of _snapshot_ events in the plist file should be the same. Knowing that, _snapshot_ automatically matches these 2 lists to identify the name of each of these screenshots. They are then copied over to the output directory and separated by language and device.
+
+2 thing have to be passed on from _snapshot_ to the `xcodebuild` command line tool:
+
+- The device type is passed via the `destination` parameter of the `xcodebuild` parameter
+- The language is passed via a temporary file which is written by _snapshot_ before running the tests and read by the UI Tests when launching the application
+
+If you find a better way to do any of this, please submit an issue on GitHub or even a pull request :+1:
+
+Radar [23062925](https://openradar.appspot.com/radar?id=5056366381105152) has been resolved with Xcode 8.3, so it's now possible to actually take screenshots from the simulator. We'll keep using the old approach for now, since many of you still want to use older versions of Xcode.
+
+# Tips
+
+<hr />
+<h4 align="center">
+  Check out the new <a href="https://docs.fastlane.tools/getting-started/ios/screenshots">fastlane documentation</a> on how to generate screenshots
+</h4>
+<hr />
+
+## Frame the screenshots
+
+If you want to add frames around the screenshots and even put a title on top, check out [frameit](https://github.com/fastlane/fastlane/tree/master/frameit).
+
+## Available language codes
+```ruby
+ALL_LANGUAGES = ["da", "de-DE", "el", "en-AU", "en-CA", "en-GB", "en-US", "es-ES", "es-MX", "fi", "fr-CA", "fr-FR", "id", "it", "ja", "ko", "ms", "nl-NL", "no", "pt-BR", "pt-PT", "ru", "sv", "th", "tr", "vi", "zh-Hans", "zh-Hant"]
+```
+
+To get more information about language and locale codes please read [Internationalization and Localization Guide](https://developer.apple.com/library/ios/documentation/MacOSX/Conceptual/BPInternational/LanguageandLocaleIDs/LanguageandLocaleIDs.html).
+
+## Use a clean status bar
+
+You can use [SimulatorStatusMagic](https://github.com/shinydevelopment/SimulatorStatusMagic) to clean up the status bar.
+
+## Editing the `Snapfile`
+
+Change syntax highlighting to *Ruby*.
+
+### Simulator doesn't launch the application
+
+When the app dies directly after the application is launched there might be 2 problems
+
+- The simulator is somehow in a broken state and you need to re-create it. You can use `snapshot reset_simulators` to reset all simulators (this will remove all installed apps)
+- A restart helps very often
+
+## Determine language
+
+To detect the currently used localization in your tests, access the `deviceLanguage` variable from `SnapshotHelper.swift`.

data/fastlane/lib/fastlane/actions/docs/supply.md

@@ -0,0 +1,144 @@
+<p align="center">
+  <img src="/img/actions/supply.png" height="110">
+</p>
+
+###### Command line tool for updating Android apps and their metadata on the Google Play Store
+
+_supply_ uploads app metadata, screenshots and binaries to Google Play. You can also select tracks for builds and promote builds to production.
+
+-------
+
+<p align="center">
+    <a href="#features">Features</a> &bull;
+    <a href="#setup">Setup</a> &bull;
+    <a href="#quick-start">Quick Start</a> &bull;
+    <a href="#available-commands">Commands</a> &bull;
+    <a href="#uploading-an-apk">Uploading an APK</a> &bull;
+    <a href="#images-and-screenshots">Images</a>
+</p>
+
+-------
+
+## Features
+- Update existing Android applications on Google Play via the command line
+- Upload new builds (APKs)
+- Retrieve and edit metadata, such as title and description, for multiple languages
+- Upload the app icon, promo graphics and screenshots for multiple languages
+- Have a local copy of the metadata in your git repository
+- Retrieve version code numbers from existing Google Play tracks
+
+
+## Setup
+
+Setup consists of setting up your Google Developers Service Account
+
+1. Open the [Google Play Console](https://play.google.com/apps/publish/)
+1. Select **Settings** tab, followed by the **API access** tab
+1. Click the **Create Service Account** button and follow the **Google API Console** link in the dialog
+1. Click the **Create Service account** button at the top of the developers console screen
+1. Provide a name for the service account
+1. Click **Select a role** and choose **Project > Service Account Actor**
+1. Check the **Furnish a new private key** checkbox
+1. Select **JSON** as the Key type
+1. Click **Create** to close the dialog
+1. Make a note of the file name of the JSON file downloaded to your computer
+1. Back on the Google Play developer console, click **Done** to close the dialog
+1. Click on **Grant Access** for the newly added service account
+1. Choose **Release Manager** from the **Role** dropdown
+1. Click **Add user** to close the dialog
+
+### Migrating Google credential format (from .p12 key file to .json)
+
+In previous versions of supply, credentials to your Play Console were stored as `.p12` files. Since version 0.4.0, supply now supports the recommended `.json` key Service Account credential files. If you wish to upgrade:
+
+- follow the <a href="#setup">Setup</a> procedure once again to make sure you create the appropriate JSON file
+- update your fastlane configuration or your command line invocation to use the appropriate argument if necessary.
+  Note that you don't need to take note nor pass the `issuer` argument anymore.
+
+
+The previous p12 configuration is still currently supported.
+
+
+## Quick Start
+
+- `cd [your_project_folder]`
+- `fastlane supply init`
+- Make changes to the downloaded metadata, add images, screenshots and/or an APK
+- `fastlane supply run`
+
+## Available Commands
+
+- `fastlane supply`: update an app with metadata, a build, images and screenshots
+- `fastlane supply init`: download metadata for an existing app to a local directory
+- `fastlane action supply`: show information on available commands, arguments and environment variables
+
+You can either run _supply_ on its own and use it interactively, or you can pass arguments or specify environment variables for all the options to skip the questions.
+
+## Uploading an APK
+
+To upload a new binary to Google Play, simply run
+
+```no-highlight
+fastlane supply --apk path/to/app.apk
+```
+
+This will also upload app metadata if you previously ran `fastlane supply init`.
+
+To gradually roll out a new build use
+
+```no-highlight
+fastlane supply --apk path/app.apk --track rollout --rollout 0.5
+```
+
+Expansion files (obbs) found under the same directory as your APK will also be uploaded together with your APK as long as:
+
+- they are identified as type 'main' or 'patch' (by containing 'main' or 'patch' in their file name)
+- you have at most one of each type
+
+## Images and Screenshots
+
+After running `fastlane supply init`, you will have a metadata directory. This directory contains one or more locale directories (e.g. en-US, en-GB, etc.), and inside this directory are text files such as `title.txt` and `short_description.txt`.
+
+Inside of a given locale directory is a folder called `images`. Here you can supply images with the following file names (extension can be png, jpg or jpeg):
+
+- `featureGraphic`
+- `icon`
+- `promoGraphic`
+- `tvBanner`
+
+And you can supply screenshots by creating directories with the following names, containing PNGs or JPEGs (image names are irrelevant):
+
+- `phoneScreenshots/`
+- `sevenInchScreenshots/` (7-inch tablets)
+- `tenInchScreenshots/` (10-inch tablets)
+- `tvScreenshots/`
+- `wearScreenshots/`
+
+Note that these will replace the current images and screenshots on the play store listing, not add to them.
+
+## Changelogs (What's new)
+
+You can add changelog files under the `changelogs/` directory for each locale. The filename should exactly match the version code of the APK that it represents. `fastlane supply init` will populate changelog files from existing data on Google Play if no `metadata/` directory exists when it is run.
+
+```no-highlight
+└── fastlane
+    └── metadata
+        └── android
+            ├── en-US
+            │   └── changelogs
+            │       ├── 100000.txt
+            │       └── 100100.txt
+            └── fr-FR
+                └── changelogs
+                    └── 100100.txt
+```
+
+## Track Promotion
+
+A common Play publishing scenario might involve uploading an APK version to a test track, testing it, and finally promoting that version to production.
+
+This can be done using the `--track_promote_to` parameter.  The `--track_promote_to` parameter works with the `--track` parameter to command the Play API to promote existing Play track APK version(s) (those active on the track identified by the `--track` param value) to a new track (`--track_promote_to` value).
+
+## Retrieve Track Version Codes
+
+Before performing a new APK upload you may want to check existing track version codes, or you may simply want to provide an informational lane that displays the currently promoted version codes for the production track. You can use the `google_play_track_version_codes` action to retrieve existing version codes for a package and track. For more information, see `fastlane action google_play_track_version_codes` help output.