screengrab 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aa8ecf68f1116cde3b751b31625d15e8e6a45cae
+  data.tar.gz: 0aa647eb1a22a6cda026710956596c3ec724465f
+SHA512:
+  metadata.gz: 396cf596e9eab3c794732b054ae6df6f974e1c3a254ee145681ee24fc335a3d99bbd5203be774f48e2fbfd708c43047bbdd26b71d1d16c47fef0e31772d550da
+  data.tar.gz: 230e1bba557341aa303a0adc39334067c8e74be1a21728e191087314209269873818152e3356699fd586d45301c17369d166eea053e3810e6d553ab99bfdf0bb

data/LICENSE

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Twitter, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Chmod.java and Screengrab.java based on work Copyright (c) Square, Inc,
+Used under permission of the Apache 2.0 License
+http://www.apache.org/licenses/LICENSE-2.0

data/README.md

@@ -0,0 +1,178 @@
+<h3 align="center">
+  <a href="https://github.com/fastlane/fastlane">
+    <img src="assets/fastlane.png" width="150" />
+    <br />
+    fastlane
+  </a>
+</h3>
+<p align="center">
+  <a href="https://github.com/fastlane/deliver">deliver</a> &bull;
+  <b>screengrab</b> &bull;
+  <a href="https://github.com/fastlane/frameit">frameit</a> &bull;
+  <a href="https://github.com/fastlane/pem">pem</a> &bull;
+  <a href="https://github.com/fastlane/sigh">sigh</a> &bull;
+  <a href="https://github.com/fastlane/produce">produce</a> &bull;
+  <a href="https://github.com/fastlane/cert">cert</a> &bull;
+  <a href="https://github.com/fastlane/spaceship">spaceship</a> &bull;
+  <a href="https://github.com/fastlane/pilot">pilot</a> &bull;
+  <a href="https://github.com/fastlane/boarding">boarding</a> &bull;
+  <a href="https://github.com/fastlane/gym">gym</a> &bull;
+  <a href="https://github.com/fastlane/scan">scan</a> &bull;
+  <a href="https://github.com/fastlane/match">match</a>
+</p>
+-------
+
+<p align="center">
+  <img src="assets/screengrab.png" height="110">
+</p>
+
+screengrab
+============
+
+[![Twitter: @FastlaneTools](https://img.shields.io/badge/contact-@FastlaneTools-blue.svg?style=flat)](https://twitter.com/FastlaneTools)
+[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat)](https://github.com/fastlane/screengrab/blob/master/LICENSE)
+[![Gem](https://img.shields.io/gem/v/screengrab.svg?style=flat)](http://rubygems.org/gems/screengrab)
+
+### Automates screenshots of your Android app
+
+Screengrab is a commandline tool that automates taking localized screenshots of your Android app.
+
+<img src="assets/running-screengrab.gif" width="640">
+
+### Why should I automate this process?
+- Create hundreds of screenshots in multiple languages on emulators or real devices, saving you hours
+- Easily verify that localizations fit into labels on all screen dimensions to find UI mistakes before you ship
+- You only need to configure it once for anyone on your team to run it
+- Keep your screenshots perfectly up-to-date with every app update. Your customers deserve it!
+- Fully integrates with [`fastlane`](https://fastlane.tools) and [`supply`](https://github.com/fastlane/supply)
+
+# Installation
+
+Once this tool is officially released, the installation will be as simple as running `gem install screengrab` For the private alpha, please follow these testing instructions:
+
+##### Command line tool installation
+1. Clone the repo with `git clone git@github.com:fastlane/screengrab.git`
+1. `cd` into your screengrab repo directory and run `rake install`
+    - You may need to `gem install bundler` if you don't already have bundler
+    - If you're using the default Ruby on Mac OS you may need to use `sudo`
+1. Run `screengrab init` to complete installation
+
+##### Gradle dependency
+```java
+androidTestCompile 'tools.fastlane:screengrab:0.1.1'
+```
+
+##### Configuring your Manifest Permissions
+Ensure that the following permissions exist in your **src/debug/AndroidManifest.xml**
+
+```xml
+<!-- Allows unlocking your device and activating its screen so UI tests can succeed -->
+<uses-permission android:name="android.permission.DISABLE_KEYGUARD"/>
+<uses-permission android:name="android.permission.WAKE_LOCK"/>
+
+<!-- Allows for storing and retrieving screenshots -->
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+
+<!-- Allows changing locales -->
+<uses-permission android:name="android.permission.CHANGE_CONFIGURATION" />
+```
+
+##### Configuring your <a href="#ui-tests">UI Tests</a> for Screenshots
+
+1.  Add `@ClassRule public static final LocaleTestRule localeTestRule = new LocaleTestRule();` to your tests class to handle automatic switching of locales
+2.  To capture screenshots, add the following to your tests `Screengrab.screenshot("name_of_screenshot_here");` on the appropriate screens
+
+# Generating Screenshots with Screengrab
+- Then, before running `screengrab` you'll need a debug and test apk
+  - You can create your APKs with `./gradlew assembleDebug assembleAndroidTest`
+- Once complete run `screengrab` in your app project directory to generate screenshots
+    - You will be prompted to provide any required parameters which are not in your **Screengrabfile** or provided as command line arguments
+- Your screenshots will be saved in a /screenshots directory in the directory where you ran `screengrab`
+
+## Advanced Screengrabfile Configuration
+
+Running `screengrab init` generated a Screengrabfile which can store all of your configuration options. Since most values will not change often for your project, it is recommended to store them there.
+
+The `Screengrabfile` is written in Ruby, so you may find it helpful to use an editor that highlights Ruby syntax to modify this file.
+
+```ruby
+# remove the leading '#' to uncomment lines
+
+# app_package_name 'your.app.package'
+# use_tests_in_packages ['your.screenshot.tests.package']
+
+# app_apk_path 'path/to/your/app.apk'
+# tests_apk_path 'path/to/your/tests.apk'
+
+locales ['en-US', 'fr-FR', 'it-IT']
+
+# clear all previously generated screenshots in your local output directory before creating new ones
+clear_previous_screenshots true
+```
+
+For more information about all available options run
+
+```
+screengrab --help
+```
+
+# Tips
+
+# UI Tests
+
+Check out [Testing UI for a Single App](http://developer.android.com/training/testing/ui-testing/espresso-testing.html) for an introduction to using Espresso for UI testing.
+
+##### Example UI Test Class (Using JUnit4)
+```java
+@RunWith(JUnit4.class)
+public class JUnit4StyleTests {
+    @ClassRule
+    public static final LocaleTestRule localeTestRule = new LocaleTestRule();
+
+    @Rule
+    public ActivityTestRule<MainActivity> activityRule = new ActivityTestRule<>(MainActivity.class);
+
+    @Test
+    public void testTakeScreenshot() {
+        Screengrab.screenshot("before_button_click");
+
+        onView(withId(R.id.fab)).perform(click());
+
+        Screengrab.screenshot("after_button_click");
+    }
+}
+
+```
+There is an [example project](https://github.com/fastlane/screengrab/tree/master/example/src/androidTest/java/io/fabric/localetester) showing how to use use JUnit 3 or 4 and Espresso with the screengrab Java library to capture screenshots during a UI test run.
+
+Using JUnit 4 is preferable because of its ability to perform actions before and after the entire test class is run. This means you will change the device's locale far fewer times when compared with JUnit 3 running those commands before and after each test method.
+
+When using JUnit 3 you'll need to add a bit more code:
+
+- Use `LocaleUtil.changeDeviceLocaleTo(LocaleUtil.getTestLocale());` in `setUp()`
+- Use `LocaleUtil.changeDeviceLocaleTo(LocaleUtil.getEndingLocale());` in `tearDown()`
+- Use `Screengrab.screenshot("name_of_screenshot_here");` to capture screenshots at the appropriate points in your tests
+
+If you're having trouble getting your device unlocked and the screen activated to run tests, try using `ScreenUtil.activateScreenForTesting(activity);` in your test setup.
+
+## [`fastlane`](https://fastlane.tools) Toolchain
+
+- [`fastlane`](https://fastlane.tools): Connect all deployment tools into one streamlined workflow
+- [`supply`](https://github.com/fastlane/supply): Upload screenshots, metadata and your app to the Play Store
+
+You can find all the tools on [fastlane.tools](https://fastlane.tools).
+
+##### [Like this tool? Be the first to know about updates and new fastlane tools](https://tinyletter.com/krausefx)
+
+# Need help?
+Please submit an issue on GitHub and provide information about your setup.
+
+## Code of Conduct
+
+Help us keep `screengrab` 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 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.

data/bin/screengrab

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+
+$:.push File.expand_path("../../lib", __FILE__)
+
+require 'screengrab'
+require 'commander'
+
+HighLine.track_eof = false
+
+class ScreengrabApplication
+  include Commander::Methods
+
+  def run
+    program :version, Screengrab::VERSION
+    program :description, 'CLI for \'screengrab\' - Automate taking localized screenshots of your Android app on emulators or real devices'
+    program :help, 'Authors', 'Andrea Falcone <afalcone@twitter.com>, Michael Furtak <mfurtak@twitter.com>'
+    program :help, 'Website', 'https://fastlane.tools'
+    program :help, 'GitHub', 'https://github.com/fastlane/screengrab'
+    program :help_formatter, :compact
+
+    global_option('--verbose', 'Shows a more verbose output') { $verbose = true }
+
+    always_trace!
+
+    FastlaneCore::CommanderGenerator.new.generate(Screengrab::Options.available_options)
+
+    command :run do |c|
+      c.syntax = 'screengrab'
+      c.description = 'Take new screenshots based on the screengrabfile.'
+
+      c.action do |args, options|
+        o = options.__hash__.dup
+        o.delete(:verbose)
+        Screengrab.config = FastlaneCore::Configuration.create(Screengrab::Options.available_options, o)
+        Screengrab.android_environment = Screengrab::AndroidEnvironment.new(Screengrab.config[:android_home],
+                                                                            Screengrab.config[:build_tools_version])
+
+        Screengrab::DependencyChecker.check(Screengrab.android_environment)
+        Screengrab::Runner.new.run
+      end
+    end
+
+    command :init do |c|
+      c.syntax = 'screengrab init'
+      c.description = "Creates a new Screengrabfile in the current directory"
+
+      c.action do |args, options|
+        require 'screengrab/setup'
+        path = (Screengrab::Helper.fastlane_enabled? ? './fastlane' : '.')
+        Screengrab::Setup.create(path)
+      end
+    end
+
+    default_command :run
+
+    run!
+  end
+end
+
+begin
+  FastlaneCore::UpdateChecker.start_looking_for_update('screengrab')
+  ScreengrabApplication.new.run
+ensure
+  FastlaneCore::UpdateChecker.show_update_status('screengrab', Screengrab::VERSION)
+end

data/lib/assets/ScreengrabfileTemplate

@@ -0,0 +1,15 @@
+# remove the leading '#' to uncomment lines
+
+# app_package_name 'your.app.package'
+# use_tests_in_packages ['your.screenshot.tests.package']
+
+# app_apk_path 'path/to/your/app.apk'
+# tests_apk_path 'path/to/your/tests.apk'
+
+locales ['en-US', 'fr-FR', 'it-IT']
+
+# clear all previously generated screenshots in your local output directory before creating new ones
+clear_previous_screenshots true
+
+# For more information about all available options run
+#   screengrab --help

data/lib/screengrab.rb

@@ -0,0 +1,31 @@
+require 'open3'
+require 'fileutils'
+
+require 'fastlane_core'
+
+require 'screengrab/version'
+require 'screengrab/runner'
+require 'screengrab/detect_values'
+require 'screengrab/dependency_checker'
+require 'screengrab/options'
+require 'screengrab/android_environment'
+
+module Screengrab
+  # Use this to just setup the configuration attribute and set it later somewhere else
+  class << self
+    attr_accessor :config
+    attr_accessor :android_environment
+
+    def config=(value)
+      @config = value
+      DetectValues.set_additional_default_values
+    end
+
+    def screengrabfile_name
+      "Screengrabfile"
+    end
+  end
+
+  Helper = FastlaneCore::Helper # you gotta love Ruby: Helper.* should use the Helper class contained in FastlaneCore
+  UI = FastlaneCore::UI
+end

data/lib/screengrab/android_environment.rb

@@ -0,0 +1,88 @@
+module Screengrab
+  class AndroidEnvironment
+    attr_reader :android_home
+    attr_reader :build_tools_version
+
+    # android_home        - the String path to the install location of the Android SDK
+    # build_tools_version - the String version of the Android build tools that should be used
+    def initialize(android_home, build_tools_version)
+      @android_home = android_home
+      @build_tools_version = build_tools_version
+    end
+
+    def platform_tools_path
+      @platform_tools_path ||= find_platform_tools(android_home)
+    end
+
+    def build_tools_path
+      @build_tools_path ||= find_build_tools(android_home, build_tools_version)
+    end
+
+    def adb_path
+      @adb_path ||= find_adb(platform_tools_path)
+    end
+
+    def aapt_path
+      @aapt_path ||= find_aapt(build_tools_path)
+    end
+
+    private
+
+    def find_platform_tools(android_home)
+      return nil unless android_home
+
+      platform_tools_path = File.join(android_home, 'platform-tools')
+      File.directory?(platform_tools_path) ? platform_tools_path : nil
+    end
+
+    def find_build_tools(android_home, build_tools_version)
+      return nil unless android_home
+
+      build_tools_dir = File.join(android_home, 'build-tools')
+
+      return nil unless build_tools_dir && File.directory?(build_tools_dir)
+
+      return File.join(build_tools_dir, build_tools_version) if build_tools_version
+
+      version = select_build_tools_version(build_tools_dir)
+
+      return version ? File.join(build_tools_dir, version) : nil
+    end
+
+    def select_build_tools_version(build_tools_dir)
+      # Collect the sub-directories of the build_tools_dir, rejecting any that start with '.' to remove . and ..
+      dir_names = Dir.entries(build_tools_dir).select { |e| !e.start_with?('.') && File.directory?(File.join(build_tools_dir, e)) }
+
+      # Collect a sorted array of Version objects from the directory names, handling the possibility that some
+      # entries may not be valid version names
+      versions = dir_names.map do |d|
+        begin
+          Gem::Version.new(d)
+        rescue
+          nil
+        end
+      end.reject(&:nil?).sort
+
+      # We'll take the last entry (highest version number) as the directory name we want
+      versions.last.to_s
+    end
+
+    def find_adb(platform_tools_path)
+      return FastlaneCore::CommandExecutor.which('adb') unless platform_tools_path
+
+      adb_path = File.join(platform_tools_path, 'adb')
+      return executable_command?(adb_path) ? adb_path : nil
+    end
+
+    def find_aapt(build_tools_path)
+      return FastlaneCore::CommandExecutor.which('aapt') unless build_tools_path
+
+      aapt_path = File.join(build_tools_path, 'aapt')
+      return executable_command?(aapt_path) ? aapt_path : nil
+    end
+
+    def executable_command?(cmd_path)
+      cmd_path && File.executable?(cmd_path) && !File.directory?(cmd_path)
+    end
+  end
+end

data/lib/screengrab/dependency_checker.rb

@@ -0,0 +1,56 @@
+module Screengrab
+  class DependencyChecker
+    def self.check(android_env)
+      return if Helper.test?
+
+      check_adb(android_env)
+      check_aapt(android_env)
+    end
+
+    def self.check_adb(android_env)
+      android_home = android_env.android_home
+      adb_path = android_env.adb_path
+
+      warn_if_command_path_not_relative_to_android_home('adb', android_home, adb_path)
+      # adb is required to function, so we'll quit noisily if we couldn't find it
+      raise_missing_adb(android_home) unless adb_path
+    end
+
+    def self.raise_missing_adb(android_home)
+      if android_home
+        UI.error "The `adb` command could not be found relative to your provided ANDROID_HOME at #{android_home}"
+        UI.error "Please ensure that the Android SDK is installed and the platform-tools directory is present"
+      else
+        UI.error 'The `adb` command could not be found on your PATH'
+        UI.error 'Please ensure that the Android SDK is installed and the platform-tools directory is present and on your PATH'
+      end
+
+      UI.user_error! 'adb command not found'
+    end
+
+    def self.check_aapt(android_env)
+      android_home = android_env.android_home
+      aapt_path = android_env.aapt_path
+
+      warn_if_command_path_not_relative_to_android_home('aapt', android_home, aapt_path)
+      # aapt is not required in order to function, so we'll only warn if we can't find it.
+      warn_missing_aapt(android_home) unless aapt_path
+    end
+
+    def self.warn_missing_aapt(android_home)
+      if android_home
+        UI.important "The `aapt` command could not be found relative to your provided ANDROID_HOME at #{android_home}"
+        UI.important "Please ensure that the Android SDK is installed and you have the build tools downloaded"
+      else
+        UI.important "The `aapt` command could not be found on your PATH"
+        UI.important "Please ensure that the Android SDK is installed and you have the build tools downloaded and present on your PATH"
+      end
+    end
+
+    def self.warn_if_command_path_not_relative_to_android_home(cmd_name, android_home, cmd_path)
+      if android_home && cmd_path && !cmd_path.start_with?(android_home)
+        UI.important "Using `#{cmd_name}` found at #{cmd_path} which is not within the specified ANDROID_HOME at #{android_home}"
+      end
+    end
+  end
+end