fastlane
deliver • snapshot • frameit • pem • sigh • produce • cert • spaceship • pilot • boarding • gym • scan • match
-------
Features • Installation • UI Tests • Quick Start • Usage • Tips • How? • Need help?
-------snapshot is part of fastlane: connect all deployment tools into one streamlined workflow.
## 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 `snapshot init`)
The `Snapfile` can contain all the options that are also available on `snapshot --help`
```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 simulators:
```
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
```
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/snapshot/blob/master/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 `NSProcessInfo.processInfo().arguments`. Alternatively use user-default syntax (`-key value`) and they will be available as key-value pairs in `NSUserDefaults.standardUserDefaults()`.
`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 NSUserDefaults.standardUserDefaults().boolForKey("FASTLANE_SNAPSHOT") {
// runtime check that we are in snapshot mode
}
username.text = NSUserDefaults.standardUserDefaults().stringForKey("username")
// username.text = "Felix"
```
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 occured 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`.
`snapshot` then iterates through all test events and check where we did this weird rotation. 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:
Also, feel free to duplicate radar [23062925](https://openradar.appspot.com/radar?id=5056366381105152).
# Tips
## [`fastlane`](https://fastlane.tools) Toolchain
- [`fastlane`](https://fastlane.tools): Connect all deployment tools into one streamlined workflow
- [`deliver`](https://github.com/fastlane/deliver): Upload screenshots, metadata and your app to the App Store
- [`frameit`](https://github.com/fastlane/frameit): Quickly put your screenshots into the right device frames
- [`PEM`](https://github.com/fastlane/pem): Automatically generate and renew your push notification profiles
- [`sigh`](https://github.com/fastlane/sigh): Because you would rather spend your time building stuff than fighting provisioning
- [`produce`](https://github.com/fastlane/produce): Create new iOS apps on iTunes Connect and Dev Portal using the command line
- [`cert`](https://github.com/fastlane/cert): Automatically create and maintain iOS code signing certificates
- [`spaceship`](https://github.com/fastlane/spaceship): Ruby library to access the Apple Dev Center and iTunes Connect
- [`pilot`](https://github.com/fastlane/pilot): The best way to manage your TestFlight testers and builds from your terminal
- [`boarding`](https://github.com/fastlane/boarding): The easiest way to invite your TestFlight beta testers
- [`gym`](https://github.com/fastlane/gym): Building your iOS apps has never been easier
- [`scan`](https://github.com/fastlane/scan): The easiest way to run tests of your iOS and Mac app
- [`match`](https://github.com/fastlane/match): Easily sync your certificates and profiles across your team using git
##### [Like this tool? Be the first to know about updates and new fastlane tools](https://tinyletter.com/krausefx)
## 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/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", "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, use the following code:
```javascript
You can access the language using the `deviceLanguage` variable.
```
# Need help?
Please submit an issue on GitHub and provide information about your setup
# Code of Conduct
Help us keep `snapshot` open and inclusive. Please read and follow our [Code of Conduct](https://github.com/fastlane/code-of-conduct).
# License
This project is licensed under the terms of the MIT license. See the LICENSE file.
> This project and all fastlane tools are in no way affiliated with Apple Inc. This project is open source under the MIT license, which means you have full access to the source code and can modify it to fit your own needs. All fastlane tools run on your own computer or server, so your credentials or other sensitive information will never leave your own computer. You are responsible for how you use fastlane tools.