calabash-cucumber 0.10.0.pre1 → 0.10.0.pre2

data/lib/calabash-cucumber/launcher.rb

@@ -9,17 +9,45 @@ require 'cfpropertylist'
 require 'calabash-cucumber/version'
 require 'calabash-cucumber/utils/logging'
 
-
+# Used to launch apps for testing in iOS Simulator or on iOS Devices.  By default
+# it uses Apple's `instruments` process to launch your app, but has legacy support
+# for using `sim_launcher`.
+#
+# ###  Accessing the current launcher from ruby.
+#
+# If you need a reference to the current launcher in your ruby code.
+# This is usually not required, but might be useful in `support/01_launch.rb`.
+#
+# `Calabash::Cucumber::Launcher.launcher`
+#
+# ### Attaching to the current launcher in a console
+#
+# If Calabash already running and you want to attach to the current launcher,
+# use `console_attach`.  This is useful when a cucumber Scenario has failed and
+# you want to query the current state of the app.
+#
+# * **Pro Tip:** set the `NO_STOP` environmental variable to 1 so calabash does
+#  not exit the simulator when a Scenario fails.
 class Calabash::Cucumber::Launcher
 
   include Calabash::Cucumber::Logging
   include Calabash::Cucumber::SimulatorAccessibility
 
+  # A hash of known privacy settings that calabash can control.
   KNOWN_PRIVACY_SETTINGS = {:photos => 'kTCCServicePhotos', :calendar => 'kTCCServiceCalendar', :address_book => 'kTCCServiceAddressBook'}
 
+  # noinspection RubyClassVariableUsageInspection
+
+  # @!visibility private
   @@launcher = nil
 
+  # @!visibility private
   SERVER_VERSION_NOT_AVAILABLE = '0.0.0'
+  # noinspection RubyClassVariableUsageInspection
+
+  # @!visibility private
+  # Class variable for caching the embedded server version so we only need to
+  # check the server version one time.
   @@server_version = nil
 
   attr_accessor :run_loop
@@ -28,6 +56,8 @@ class Calabash::Cucumber::Launcher
   attr_accessor :launch_args
   attr_accessor :simulator_launcher
 
+  # @!visibility private
+  # Generated when calabash cannot launch the app.
   class StartError < RuntimeError
     attr_accessor :error
 
@@ -35,31 +65,37 @@ class Calabash::Cucumber::Launcher
       self.error= err
     end
 
+    # @!visibility private
     def to_s
       "#{super.to_s}: #{error}"
     end
   end
 
+  # @!visibility private
+  # Generated when calabash cannot communicate with the app.
   class CalabashLauncherTimeoutErr < Timeout::Error
   end
 
-
+  # @!visibility private
   def initialize
     @simulator_launcher = Calabash::Cucumber::SimulatorLauncher.new
     @@launcher = self
   end
 
+  # @!visibility private
   def actions
     attach if @actions.nil?
     @actions
   end
 
+  # @see Calabash::Cucumber::Core#console_attach
   def self.attach
     l = launcher
     return l if l && l.active?
     l.attach
   end
 
+  # @see Calabash::Cucumber::Core#console_attach
   def attach(max_retry=1, timeout=10)
     if calabash_no_launch?
       self.actions= Calabash::Cucumber::PlaybackActions.new
@@ -95,20 +131,30 @@ class Calabash::Cucumber::Launcher
     self
   end
 
+  # Are we running using instruments?
+  #
+  # @return {Boolean} true if we're using instruments to launch
   def self.instruments?
     l = launcher_if_used
     return false unless l
     l.instruments?
   end
 
+  # Get a reference to the current launcher (instantiates a new one if needed). Usually we use a singleton launcher throughout a test run.
+  # @return {Calabash::Cucumber::Launcher} the current launcher
   def self.launcher
     @@launcher ||= Calabash::Cucumber::Launcher.new
   end
 
+  # Get a reference to the current launcher (does not instantiate a new one if unset).
+  # Usually we use a singleton launcher throughout a test run.
+  # @return {Calabash::Cucumber::Launcher} the current launcher or nil
   def self.launcher_if_used
     @@launcher
   end
 
+  # "Major" component of the current iOS version of the device
+  # @return {String} the "major" component, e.g., "7" for "7.1.1"
   def ios_major_version
     # pinging the app will set self.device
     ping_app if self.device.nil?
@@ -117,36 +163,141 @@ class Calabash::Cucumber::Launcher
     device.ios_major_version
   end
 
+  # the current iOS version of the device
+  # @return {String} the current iOS version of the device
   def ios_version
     return nil if device.nil?
     device.ios_version
   end
 
+  # @deprecated 0.10.0 Replaced with {#reset_app_sandbox}.
+  # Reset the app sandbox for a device.
   def reset_app_jail(sdk=nil, path=nil)
-    sdk ||= sdk_version || self.simulator_launcher.sdk_detector.latest_sdk_version
-    path ||= self.simulator_launcher.app_bundle_or_raise(app_path)
+    # will be deprecated in a future version
+    #_deprecated('0.10.0', 'use reset_app_sandbox instead', :warn)
+    reset_app_sandbox({:sdk => sdk, :path => path})
+  end
+
+  # Resets the app's content and settings by deleting the following directories
+  # from application sandbox:
+  #
+  # * Library
+  # * Documents
+  # * tmp
+  #
+  # @note It is not recommended that you call this method directly.  See the
+  #  examples below for how use the `RESET_BETWEEN_SCENARIOS` environmental
+  #  variable to reset the app sandbox.
+  #
+  # @note This method is only available for the iOS Simulator.
+  #
+  # @note Generates a warning if called when targeting a physical device and
+  #  otherwise has no effect.
+  #
+  # @note When testing against the Xamarin Test Cloud, this method is never
+  #  called.  Use the `RESET_BETWEEN_SCENARIOS` environmental variable.
+  #  See the examples.
+  #
+  # @example Use `RESET_BETWEEN_SCENARIOS` to reset the app sandbox before every Scenario.
+  #  When testing devices outside the Xamarin Test Cloud this has no effect.
+  #
+  #  On the Xamarin Test Cloud, the app sandbox will be reset, but this method
+  #  will not be called; the resetting is done via an alternative mechanism.
+  #
+  #  When testing simulators, this method will be called.
+  #
+  #  Launch cucumber with RESET_BETWEEN_SCENARIOS=1
+  #
+  #  $ RESET_BETWEEN_SCENARIOS=1 bundle exec cucumber
+  #
+  # @example Use tags and a Before hook to reset the app sandbox before specific Scenarios.
+  #  # in your .feature file
+  #
+  #  @reset_app_before_hook
+  #  Scenario:  some scenario that requires the app be reset
+  #
+  #  # in your support/01_launch.rb file
+  #  #
+  #  # 1. add a Before hook
+  #  Before('@reset_app_before_hook') do
+  #    ENV['RESET_BETWEEN_SCENARIOS'] = '1'
+  #  end
+  #
+  #  # 2. after launching, revert the env var value
+  #  Before do |scenario|
+  #    # launch the app
+  #    launcher = Calabash::Cucumber::Launcher.new
+  #    unless launcher.calabash_no_launch?
+  #      launcher.relaunch
+  #      launcher.calabash_notify(self)
+  #    end
+  #    # disable resetting between Scenarios
+  #    ENV['RESET_BETWEEN_SCENARIOS'] = ''
+  #  end
+  #
+  # @param [Hash] opts can pass the target sdk or the path to the application bundle
+  # @option opts [String, Symbol] :sdk (nil) The target sdk.  If nil is
+  #  passed, then only app sandbox for the latest sdk will be deleted.  If
+  #  `:all` is passed, then the sandboxes for all sdks will be deleted.
+  # @option opts [String] :path (nil) path to the application bundle
+  def reset_app_sandbox(opts={})
+
+    if device_target?
+      calabash_warn("calling 'reset_app_sandbox' when targeting a device.")
+      return
+    end
+
+    default_opts = {:sdk => nil, :path => nil}
+    merged_opts = default_opts.merge opts
+
+    sdk ||= merged_opts[:sdk] || sdk_version || self.simulator_launcher.sdk_detector.latest_sdk_version
+    path ||= merged_opts[:path] || self.simulator_launcher.app_bundle_or_raise(app_path)
 
     app = File.basename(path)
-    directories_for_sdk_prefix(sdk).each do |dir|
-      bundle = `find "#{dir}/Applications" -type d -depth 2 -name "#{app}" | head -n 1`
+
+    directories_for_sdk_prefix(sdk).each do |sdk_dir|
+      app_dir = File.expand_path("#{sdk_dir}/Applications")
+      next unless File.exists?(app_dir)
+
+      bundle = `find "#{app_dir}" -type d -depth 2 -name "#{app}" | head -n 1`
+
       next if bundle.empty? # Assuming we're already clean
+
       if debug_logging?
         puts "Reset app state for #{bundle}"
       end
       sandbox = File.dirname(bundle)
-      ['Library', 'Documents', 'tmp'].each do |dir|
-        FileUtils.rm_rf(File.join(sandbox, dir))
+      ['Library', 'Documents', 'tmp'].each do |content_dir|
+        FileUtils.rm_rf(File.join(sandbox, content_dir))
       end
     end
+  end
 
-
+  # Simulates touching the iOS Simulator > Reset Content and Settings... menu
+  # item.
+  #
+  # @note
+  #  **WARNING** This is a destructive operation.  You have been warned.
+  #
+  # @raise RuntimeError if called when targeting a physical device
+  def reset_simulator
+    if device_target?
+      raise "calling 'reset_simulator' when targeting a device is not allowed"
+    end
+    reset_simulator_content_and_settings
   end
 
+  # @!visibility private
   def directories_for_sdk_prefix(sdk)
-    Dir["#{ENV['HOME']}/Library/Application Support/iPhone Simulator/#{sdk}*"]
+    if sdk == :all
+      existing_simulator_support_sdk_dirs
+    else
+      Dir["#{simulator_app_support_dir}/#{sdk}*"]
+    end
   end
 
-  # Call as update_privacy_settings('com.my.app', {:photos => {:allow => true}})
+  # Call as `update_privacy_settings('com.my.app', {:photos => {:allow => true}})`
+  # @!visibility private
   def update_privacy_settings(bundle_id, opts={})
     if debug_logging?
       puts "Update privacy settings #{bundle_id}, #{opts}"
@@ -191,13 +342,14 @@ class Calabash::Cucumber::Launcher
         end
       end
     end
-
   end
 
+  # @!visibility private
   def tcc_database_for_sdk_dir(dir)
     File.join(dir,'Library', 'TCC', 'TCC.db')
   end
 
+  # @!visibility private
   def privacy_setting(sdk_dir, bundle_id, setting_name)
     setting_name = KNOWN_PRIVACY_SETTINGS[setting_name] || setting_name
     path_to_tcc_db = tcc_database_for_sdk_dir(sdk_dir)
@@ -207,6 +359,7 @@ class Calabash::Cucumber::Launcher
     (output == '0' || output == '1') ? output.to_i : nil
   end
 
+  # @!visibility private
   def default_launch_args
     # APP_BUNDLE_PATH
     # BUNDLE_ID
@@ -249,11 +402,12 @@ class Calabash::Cucumber::Launcher
     end
 
     if args[:device_target].nil?
-      args[:device_target] = 'simulator'
+      args[:device_target] = device_tgt || 'simulator'
     end
     args
   end
 
+  # @!visibility private
   def detect_connected_device?
     if ENV['DETECT_CONNECTED_DEVICE'] == '1'
       return true
@@ -272,6 +426,7 @@ class Calabash::Cucumber::Launcher
     return false
   end
 
+  # @!visibility private
   def default_launch_method
     sdk = sdk_version
     major = nil
@@ -298,7 +453,35 @@ class Calabash::Cucumber::Launcher
     end
   end
 
+  # Launches your app on the connected device or simulator. Stops the app if it is already running.
+  # `relaunch` does a lot of error detection and handling to reliably start the app and test. Instruments (particularly the cli)
+  # has stability issues which we workaround by restarting the simulator process and checking that UIAutomation is correctly
+  # attaching.
+  #
+  # Takes optional args to specify details of the launch (e.g. device or simulator, sdk version, target device, launch method...).
+  # @note an important part of relaunch behavior is controlled by environment variables, specified below
+  #
+  # The two most important environment variables are `DEVICE_TARGET` and `APP_BUNDLE_PATH`.
+  #
+  # - `DEVICE_TARGET` controls which device you're running on. To see the options run: `instruments -s devices`.
+  #   In addition you can specify `DEVICE_TARGET=device` to run on a (unique) usb-connected device.
+  # - `APP_BUNDLE_PATH` controls which `.app` bundle to launch in simulator (don't use for on-device testing, instead use `BUNDLE_ID`).
+  # - `BUNDLE_ID` used with `DEVICE_TARGET=device` to specify which app to launch on device
+  # - `DEBUG` - set to "1" to obtain debug info (typically used to debug launching, UIAutomation and other issues)
+  # - `DEBUG_HTTP` - set to "1" to show raw HTTP traffic
+  #
+  #
+  # @example Launching on iPad simulator with DEBUG settings
+  #   DEBUG_HTTP=1 DEVICE_TARGET="iPad - Simulator - iOS 7.1" DEBUG=1 APP_BUNDLE_PATH=FieldServiceiOS.app bundle exec calabash-ios console
+  # @param {Hash} args optional args to specify details of the launch (e.g. device or simulator, sdk version,
+  #   target device, launch method...).
+  # @option args {String} :app (detect the location of the bundle from project settings) app bundle path
+  # @option args {String} :bundle_id if launching on device, specify this or env `BUNDLE_ID` to be the bundle identifier
+  #   of the application to launch
+  # @option args {Hash} :privacy_settings preset privacy settings for the, e.g., `{:photos => {:allow => true}}`.
+  #    See {KNOWN_PRIVACY_SETTINGS}
   def relaunch(args={})
+    #TODO stopping is currently broken, but this works anyway because instruments stop the process before relaunching
     RunLoop.stop(run_loop) if run_loop
 
     args = default_launch_args.merge(args)
@@ -330,9 +513,25 @@ class Calabash::Cucumber::Launcher
 
     args[:device] ||= detect_device_from_args(args)
 
-
-    reset_app_jail if args[:reset]
-
+    if simulator_target?(args) and args[:reset]
+      # attempt to find the sdk version from the :device_target
+      sdk = sdk_version_for_simulator_target(args)
+
+      # *** LEGACY SUPPORT ***
+      # If DEVICE_TARGET has not been set and is not a device UDID, then
+      # :device_target will be 'simulator'.  In that case, we cannot know what
+      # SDK version of the app sandbox we should reset.  The user _might_ give
+      # us a hint with SDK_VERSION, but we want to deprecate that variable ASAP.
+      #
+      # If passed a nil SDK arg, reset_app_sandbox will reset the _latest_ SDK.
+      # This is not good, because this is probably _not_ the SDK that should be
+      # reset.  Our only option is to reset every sandbox for all SDKs by
+      # passing :sdk => :all to reset_app_sandbox.
+      if sdk.nil? and args[:device_target] == 'simulator'
+        sdk = :all
+      end
+      reset_app_sandbox({:sdk => sdk, :path => args[:app]})
+    end
 
     if args[:privacy_settings]
       if simulator_target?(args)
@@ -361,6 +560,7 @@ class Calabash::Cucumber::Launcher
     check_server_gem_compatibility
   end
 
+  # @!visibility private
   def detect_device_from_args(args)
     if args[:app] && File.directory?(args[:app])
       # Derive bundle id from bundle_dir
@@ -379,11 +579,9 @@ class Calabash::Cucumber::Launcher
     else
       args[:app]
     end
-
-
   end
 
-  # todo this method should be migrated to the Simulator Launcher
+  # @!visibility private
   def detect_app_bundle_from_args(args)
     if simulator_target?(args)
       device_xamarin_build_dir = 'iPhoneSimulator'
@@ -394,6 +592,7 @@ class Calabash::Cucumber::Launcher
     self.simulator_launcher.detect_app_bundle(nil, device_xamarin_build_dir)
   end
 
+  # @!visibility private
   def detect_bundle_id_from_app_bundle(args)
     if args[:app] && File.directory?(args[:app])
       # Derive bundle id from bundle_dir
@@ -406,11 +605,13 @@ class Calabash::Cucumber::Launcher
     end
   end
 
+  # @!visibility private
   def info_plist_from_bundle_path(bundle_path)
     plist_path = File.join(bundle_path, 'Info.plist')
     info_plist_as_hash(plist_path) if File.exist?(plist_path)
   end
 
+  # @!visibility private
   def new_run_loop(args)
 
     # for stability, quit the simulator if Xcode version is > 5.1 and the
@@ -441,6 +642,7 @@ class Calabash::Cucumber::Launcher
     raise StartError.new(last_err)
   end
 
+  # @!visibility private
   def ensure_connectivity(max_retry=10, timeout=30)
     begin
       max_retry_count = (ENV['MAX_CONNECT_RETRY'] || max_retry).to_i
@@ -484,6 +686,7 @@ class Calabash::Cucumber::Launcher
     end
   end
 
+  # @!visibility private
   def ping_app
     url = URI.parse(ENV['DEVICE_ENDPOINT']|| "http://localhost:37265/")
 
@@ -506,17 +709,19 @@ class Calabash::Cucumber::Launcher
     status
   end
 
+  # @!visibility private
   def stop
     RunLoop.stop(run_loop) if run_loop && run_loop[:pid]
   end
 
+  # @!visibility private
   def calabash_notify(world)
     if world.respond_to?(:on_launch)
       world.on_launch
     end
   end
 
-
+  # @!visibility private
   def info_plist_as_hash(plist_path)
     unless File.exist?(plist_path)
       raise "Unable to find Info.plist: #{plist_path}"
@@ -525,6 +730,7 @@ class Calabash::Cucumber::Launcher
     CFPropertyList.native_types(parsedplist.value)
   end
 
+  # @!visibility private
   def detect_bundle_id
     begin
       bundle_path = self.simulator_launcher.app_bundle_or_raise(app_path)
@@ -535,60 +741,91 @@ class Calabash::Cucumber::Launcher
     end
   end
 
+  # @!visibility private
   def calabash_no_stop?
     calabash_no_launch? or ENV['NO_STOP']=="1"
   end
 
+  # @!visibility private
   def calabash_no_launch?
     ENV['NO_LAUNCH']=='1'
   end
 
+  # @!visibility private
   def device_target?
     (ENV['DEVICE_TARGET'] != nil) && (not simulator_target?)
   end
 
+  # @!visibility private
   def simulator_target?(launch_args={})
     value = ENV['DEVICE_TARGET'] || launch_args[:device_target]
     return false if value.nil?
     value.downcase.include?('simulator')
   end
 
+  # @!visibility private
   def sdk_version
     ENV['SDK_VERSION']
   end
 
+  # @!visibility private
+  def sdk_version_for_simulator_target(launch_args)
+    return nil if device_target?
+    value = launch_args[:device_target]
+    return nil if value.nil?
+    return nil unless value.downcase.include?('simulator')
+    # we have a string like:
+    # iPhone Retina (4-inch) - Simulator - iOS 7.1
+    # iPad Retina - Simulator - iOS 6.1
+    # iPhone Retina (4-inch 64-bit) - Simulator - iOS 7.0
+    sdk = value.split(' ').last
+
+    # legacy support for DEVICE_TARGET=simulator
+    return nil if sdk == 'simulator'
+    sdk
+  end
+
+  # @!visibility private
   def use_instruments_env?
     ENV['LAUNCH_VIA'] == 'instruments'
   end
 
+  # @!visibility private
   def use_sim_launcher_env?
     ENV['LAUNCH_VIA'] == 'sim_launcher'
   end
 
+  # @!visibility private
   def reset_between_scenarios?
     ENV['RESET_BETWEEN_SCENARIOS']=="1"
   end
 
+  # @!visibility private
   def device_env
     ENV['DEVICE']
   end
 
+  # @!visibility private
   def app_path
     ENV['APP_BUNDLE_PATH'] || (defined?(APP_BUNDLE_PATH) && APP_BUNDLE_PATH) || ENV['APP']
   end
 
+  # @!visibility private
   def run_with_instruments?(args)
     args && args[:launch_method] == :instruments
   end
 
+  # @!visibility private
   def active?
     not run_loop.nil?
   end
 
+  # @!visibility private
   def instruments?
     !!(active? && run_loop[:pid])
   end
 
+  # @!visibility private
   def inspect
     msg = ["#{self.class}: Launch Method #{launch_args && launch_args[:launch_method]}"]
     if run_with_instruments?(self.launch_args) && self.run_loop
@@ -597,17 +834,19 @@ class Calabash::Cucumber::Launcher
     msg.join("\n")
   end
 
-  # extracts server version from the app binary at +app_bundle_path+ by
+  # @!visibility private
+  # Extracts server version from the app binary at `app_bundle_path` by
   # inspecting the binary's strings table.
   #
-  # SPECIAL: sets the +@@server_version+ class variable to cache the server
-  # version because the server version will never change during runtime.
+  # @note
+  #  SPECIAL: sets the `@@server_version` class variable to cache the server
+  #  version because the server version will never change during runtime.
   #
   # @return [String] the server version
   # @param [String] app_bundle_path file path (usually) to the application bundle
-  # @raise [RuntimeError] if there is no executable at +app_bundle_path+
+  # @raise [RuntimeError] if there is no executable at `app_bundle_path`
   # @raise [RuntimeError] if the server version cannot be extracted from any
-  #   binary at +app_bundle_path+
+  #   binary at `app_bundle_path`
   def server_version_from_bundle(app_bundle_path)
     return @@server_version unless @@server_version.nil?
     exe_paths = []
@@ -665,6 +904,7 @@ class Calabash::Cucumber::Launcher
   # WIP:  this is a proof-of-concept implementation and requires _strict_
   # equality.  in the future we should allow minimum framework compatibility.
   #
+  # @!visibility private
   # @return [nil] nothing to return
   def check_server_gem_compatibility
     app_bundle_path = self.launch_args[:app]