run_loop_tcc 2.1.3

data/lib/run_loop/core.rb

@@ -0,0 +1,902 @@
+require 'fileutils'
+require 'tmpdir'
+require 'timeout'
+require 'json'
+require 'open3'
+require 'erb'
+require 'ap'
+
+module RunLoop
+
+  module Core
+
+    include RunLoop::Regex
+
+    START_DELIMITER = "OUTPUT_JSON:\n"
+    END_DELIMITER="\nEND_OUTPUT"
+
+    SCRIPTS = {
+      :dismiss => 'run_dismiss_location.js',
+      :run_loop_host => 'run_loop_host.js',
+      :run_loop_fast_uia => 'run_loop_fast_uia.js',
+      :run_loop_shared_element => 'run_loop_shared_element.js',
+      :run_loop_basic => 'run_loop_basic.js'
+    }
+
+    SCRIPTS_PATH = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'scripts'))
+    READ_SCRIPT_PATH = File.join(SCRIPTS_PATH, 'read-cmd.sh')
+    TIMEOUT_SCRIPT_PATH = File.join(SCRIPTS_PATH, 'timeout3')
+
+    def self.log_run_loop_options(options, xcode)
+      return unless RunLoop::Environment.debug?
+      # Ignore :sim_control b/c it is a ruby object; printing is not useful.
+      ignored_keys = [:sim_control]
+      options_to_log = {}
+      options.each_pair do |key, value|
+        next if ignored_keys.include?(key)
+        options_to_log[key] = value
+      end
+      # Objects that override '==' cannot be printed by awesome_print
+      # https://github.com/michaeldv/awesome_print/issues/154
+      # RunLoop::Version overrides '=='
+      options_to_log[:xcode] = xcode.version.to_s
+      options_to_log[:xcode_path] = xcode.developer_dir
+      message = options_to_log.ai({:sort_keys => true})
+      logger = options[:logger]
+      RunLoop::Logging.log_debug(logger, "\n" + message)
+    end
+
+    def self.script_for_key(key)
+      if SCRIPTS[key].nil?
+        return nil
+      end
+      SCRIPTS[key]
+    end
+
+    # @!visibility private
+    # This is the entry point for UIAutomation.
+    def self.run_with_options(options)
+      before = Time.now
+
+      self.prepare(options)
+
+      logger = options[:logger]
+      simctl = options[:sim_control] || options[:simctl] || RunLoop::Simctl.new
+      xcode = options[:xcode] || RunLoop::Xcode.new
+      instruments = options[:instruments] || RunLoop::Instruments.new
+
+      if xcode.version_gte_8?
+        raise %Q[
+UIAutomation is not available on Xcode >= 8.*.
+
+We are in the process of updating Calabash to use our new tool: DeviceAgent.
+
+We will track progress in this forum post:
+
+https://groups.google.com/forum/#!topic/calabash-ios/g34znf0LnE4
+
+For now, testing with Xcode 8 is not supported.
+
+Thank you for your patience.
+]
+      end
+
+      # Device under test: DUT
+      device = RunLoop::Device.detect_device(options, xcode, simctl, instruments)
+
+      # App under test: AUT
+      app_details = RunLoop::DetectAUT.detect_app_under_test(options)
+
+      # Find the script to pass to instruments and the strategy to communicate
+      # with UIAutomation.
+      script_n_strategy = self.detect_instruments_script_and_strategy(options,
+                                                                      device,
+                                                                      xcode)
+      instruments_script = script_n_strategy[:script]
+      uia_strategy = script_n_strategy[:strategy]
+
+      # The app life cycle reset options.
+      reset_options = self.detect_reset_options(options)
+
+      instruments.kill_instruments(xcode)
+
+      timeout = options[:timeout] || 30
+
+      results_dir = options[:results_dir] || RunLoop::DotDir.make_results_dir
+      results_dir_trace = File.join(results_dir, 'trace')
+      FileUtils.mkdir_p(results_dir_trace)
+
+      dependencies = options[:dependencies] || []
+      dependencies << File.join(SCRIPTS_PATH, 'calabash_script_uia.js')
+      dependencies.each do |dep|
+        FileUtils.cp(dep, results_dir)
+      end
+
+      script = File.join(results_dir, '_run_loop.js')
+
+      javascript = UIAScriptTemplate.new(SCRIPTS_PATH, instruments_script).result
+      UIAScriptTemplate.sub_path_var!(javascript, results_dir)
+      UIAScriptTemplate.sub_read_script_path_var!(javascript, READ_SCRIPT_PATH)
+      UIAScriptTemplate.sub_timeout_script_path_var!(javascript, TIMEOUT_SCRIPT_PATH)
+
+      # Using a :no_* option is confusing.
+      # TODO Replace :no_flush with :flush_uia_logs; it should default to true
+      if RunLoop::Environment.xtc?
+        UIAScriptTemplate.sub_mode_var!(javascript, "FLUSH") unless options[:no_flush]
+      else
+        if self.detect_flush_uia_log_option(options)
+          UIAScriptTemplate.sub_flush_uia_logs_var!(javascript, "FLUSH_LOGS")
+        end
+      end
+
+      repl_path = File.join(results_dir, 'repl-cmd.pipe')
+      FileUtils.rm_f(repl_path)
+
+      if uia_strategy == :host
+        create_uia_pipe(repl_path)
+      else
+        FileUtils.touch repl_path
+      end
+
+      RunLoop::HostCache.default.clear unless RunLoop::Environment.xtc?
+
+      cal_script = File.join(SCRIPTS_PATH, 'calabash_script_uia.js')
+      File.open(script, 'w') do |file|
+        if include_calabash_script?(options)
+          file.puts IO.read(cal_script)
+        end
+        file.puts javascript
+      end
+
+      args = options.fetch(:args, [])
+
+      log_file = options[:log_path] || File.join(results_dir, 'run_loop.out')
+
+      discovered_options =
+        {
+          :udid => device.udid,
+          :device => device,
+          :results_dir_trace => results_dir_trace,
+          :bundle_id => app_details[:bundle_id],
+          :app => app_details[:app]  || app_details[:bundle_id],
+          :results_dir => results_dir,
+          :script => script,
+          :log_file => log_file,
+          :args => args,
+          :uia_strategy => uia_strategy,
+          :base_script => instruments_script
+        }
+      merged_options = options.merge(discovered_options)
+
+      if device.simulator?
+        if !app_details[:app]
+          raise %Q[
+
+Invalid APP, APP_BUNDLE_PATH, or BUNDLE_ID detected.
+
+The following information was detected from the environment:
+
+             APP='#{ENV["APP"]}'
+ APP_BUNDLE_PATH='#{ENV["APP_BUNDLE_PATH"]}'
+       BUNDLE_ID='#{ENV["BUNDLE_ID"]}'
+
+
+It looks like you are trying to launch an app on a simulator using a bundle
+identifier or you have incorrectly set the APP variable to an app bundle that
+does not exist.
+
+If you are trying to launch a test against a physical device, set the DEVICE_TARGET
+variable to the UDID of your device an APP to a bundle identifier or a path to
+an .ipa.
+
+# com.example.MyApp must be installed on the target device
+$ APP=com.example.MyApp DEVICE_TARGET="John's iPhone" cucumber
+
+If you are trying to launch against a simulator and you encounter this error, it
+means that the APP variable is pointing to a .app that does not exist.
+
+]
+        end
+        self.prepare_simulator(app_details[:app], device, xcode, simctl, reset_options)
+      end
+
+      self.log_run_loop_options(merged_options, xcode)
+
+      automation_template = automation_template(instruments)
+
+      RunLoop::Logging.log_header(logger, "Starting on #{device.name} App: #{app_details[:bundle_id]}")
+
+      pid = instruments.spawn(automation_template, merged_options, log_file)
+
+      File.open(File.join(results_dir, 'run_loop.pid'), 'w') do |f|
+        f.write pid
+      end
+
+      run_loop = {
+        :pid => pid,
+        :index => 1,
+        :uia_strategy => uia_strategy,
+        :udid => device.udid,
+        :app => app_details[:bundle_id],
+        :repl_path => repl_path,
+        :log_file => log_file,
+        :results_dir => results_dir
+      }
+
+      uia_timeout = options[:uia_timeout] || RunLoop::Environment.uia_timeout || 10
+
+      RunLoop::Logging.log_debug(logger, "Preparation took #{Time.now-before} seconds")
+
+      before_instruments_launch = Time.now
+
+      fifo_retry_on = [
+        RunLoop::Fifo::NoReaderConfiguredError,
+        RunLoop::Fifo::WriteTimedOut
+      ]
+
+      begin
+
+        if options[:validate_channel]
+          options[:validate_channel].call(run_loop, 0, uia_timeout)
+        else
+
+          cmd = "UIALogger.logMessage('Listening for run loop commands')"
+
+          begin
+
+            fifo_timeout = options[:fifo_timeout] || 30
+            RunLoop::Fifo.write(repl_path, "0:#{cmd}", timeout: fifo_timeout)
+
+          rescue *fifo_retry_on => e
+
+            message = "Error while writing to fifo. #{e}"
+            RunLoop::Logging.log_debug(logger, message)
+            raise RunLoop::TimeoutError.new(message)
+
+          end
+
+          Timeout::timeout(timeout, RunLoop::TimeoutError) do
+            read_response(run_loop, 0, uia_timeout)
+          end
+
+        end
+      rescue RunLoop::TimeoutError => e
+        RunLoop::Logging.log_debug(logger, "Failed to launch. #{e}: #{e && e.message}")
+
+        message = %Q(
+
+"Timed out waiting for UIAutomation run-loop #{e}.
+
+Logfile: #{log_file}
+
+        #{File.read(log_file)}
+
+        )
+        raise RunLoop::TimeoutError, message
+      end
+
+      RunLoop::Logging.log_debug(logger, "Launching took #{Time.now-before_instruments_launch} seconds")
+
+      dylib_path = self.dylib_path_from_options(merged_options)
+
+      if dylib_path
+        if device.physical_device?
+          raise RuntimeError, "Injecting a dylib is not supported when targeting a device"
+        end
+
+        app = app_details[:app]
+        lldb = RunLoop::DylibInjector.new(app.executable_name, dylib_path)
+        lldb.retriable_inject_dylib
+      end
+
+      RunLoop.log_debug("It took #{Time.now - before} seconds to launch the app")
+      run_loop
+    end
+
+    # @!visibility private
+    # Usually we include CalabashScript to ease uia automation.
+    # However in certain scenarios we don't load it since
+    # it slows down the UIAutomation initialization process
+    # occasionally causing privacy/security dialogs not to be automated.
+    #
+    # @return {boolean} true if CalabashScript should be loaded
+    def self.include_calabash_script?(options)
+
+      if (options[:include_calabash_script] == false) || options[:dismiss_immediate_dialogs]
+        return false
+      end
+      if Core.script_for_key(:run_loop_basic) == options[:script]
+        return options[:include_calabash_script]
+      end
+      true
+    end
+
+    # Extracts the value of :inject_dylib from options Hash.
+    # @param options [Hash] arguments passed to {RunLoop.run}
+    # @return [String, nil] If the options contains :inject_dylibs and it is a
+    #  path to a dylib that exists, return the path.  Otherwise return nil or
+    #  raise an error.
+    # @raise [RuntimeError] If :inject_dylib points to a path that does not exist.
+    # @raise [ArgumentError] If :inject_dylib is not a String.
+    def self.dylib_path_from_options(options)
+      inject_dylib = options.fetch(:inject_dylib, nil)
+      return nil if inject_dylib.nil?
+      unless inject_dylib.is_a? String
+        raise ArgumentError, "Expected :inject_dylib to be a path to a dylib, but found '#{inject_dylib}'"
+      end
+      dylib_path = File.expand_path(inject_dylib)
+      unless File.exist?(dylib_path)
+        raise "Cannot load dylib.  The file '#{dylib_path}' does not exist."
+      end
+      dylib_path
+    end
+
+    # Returns the a default simulator to target.  This default needs to be one
+    # that installed by default in the current Xcode version.
+    #
+    # For historical reasons, the most recent non-64b SDK should be used.
+    #
+    # @param [RunLoop::Xcode] xcode Used to detect the current xcode
+    #  version.
+    def self.default_simulator(xcode=RunLoop::Xcode.new)
+
+      if xcode.version_gte_8?
+        "iPhone 6s (10.0)"
+      elsif xcode.version_gte_73?
+        "iPhone 6s (9.3)"
+      elsif xcode.version_gte_72?
+        "iPhone 6s (9.2)"
+      elsif xcode.version_gte_71?
+        "iPhone 6s (9.1)"
+      elsif xcode.version_gte_7?
+        "iPhone 5s (9.0)"
+      elsif xcode.version_gte_64?
+        "iPhone 5s (8.4 Simulator)"
+      elsif xcode.version_gte_63?
+        "iPhone 5s (8.3 Simulator)"
+      elsif xcode.version_gte_62?
+        "iPhone 5s (8.2 Simulator)"
+      elsif xcode.version_gte_61?
+        "iPhone 5s (8.1 Simulator)"
+      else
+        "iPhone 5s (8.0 Simulator)"
+      end
+    end
+
+
+    def self.create_uia_pipe(repl_path)
+      begin
+        Timeout::timeout(5, RunLoop::TimeoutError) do
+          loop do
+            begin
+              FileUtils.rm_f(repl_path)
+              return repl_path if system(%Q[mkfifo "#{repl_path}"])
+            rescue Errno::EINTR => _
+              sleep(0.1)
+            end
+          end
+        end
+      rescue RunLoop::TimeoutError => _
+        raise RunLoop::TimeoutError, 'Unable to create pipe (mkfifo failed)'
+      end
+    end
+
+    def self.jruby?
+      RUBY_PLATFORM == 'java'
+    end
+
+    def self.write_request(run_loop, cmd, logger=nil)
+      repl_path = run_loop[:repl_path]
+      index = run_loop[:index]
+      cmd_str = "#{index}:#{escape_host_command(cmd)}"
+      RunLoop::Logging.log_debug(logger, cmd_str)
+      write_succeeded = false
+      2.times do |i|
+        RunLoop::Logging.log_debug(logger, "Trying write of command #{cmd_str} at index #{index}")
+        begin
+          RunLoop::Fifo.write(repl_path, cmd_str)
+          write_succeeded = validate_index_written(run_loop, index, logger)
+        rescue RunLoop::Fifo::NoReaderConfiguredError,
+          RunLoop::Fifo::WriteTimedOut => e
+          RunLoop::Logging.log_debug(logger, "Error while writing command (retry count #{i}). #{e}")
+        end
+        break if write_succeeded
+      end
+      unless write_succeeded
+        RunLoop::Logging.log_debug(logger, 'Failing...Raising RunLoop::WriteFailedError')
+        raise RunLoop::WriteFailedError.new("Trying write of command #{cmd_str} at index #{index}")
+      end
+      run_loop[:index] = index + 1
+      RunLoop::HostCache.default.write(run_loop) unless RunLoop::Environment.xtc?
+      index
+    end
+
+    def self.validate_index_written(run_loop, index, logger)
+      begin
+        Timeout::timeout(10, RunLoop::TimeoutError) do
+          Core.read_response(run_loop, index, 10, 'last_index')
+        end
+        RunLoop::Logging.log_debug(logger, "validate index written for index #{index} ok")
+        return true
+      rescue RunLoop::TimeoutError => _
+        RunLoop::Logging.log_debug(logger, "validate index written for index #{index} failed. Retrying.")
+        return false
+      end
+    end
+
+    def self.escape_host_command(cmd)
+      backquote = "\\"
+      cmd.gsub(backquote,backquote*4)
+    end
+
+    def self.log_instruments_error(msg)
+      $stderr.puts "\033[31m\n\n*** #{msg} ***\n\n\033[0m"
+      $stderr.flush
+    end
+
+    def self.read_response(run_loop, expected_index, empty_file_timeout=10, search_for_property='index')
+      debug_read = RunLoop::Environment.debug_read?
+
+      log_file = run_loop[:log_file]
+      initial_offset = run_loop[:initial_offset] || 0
+      offset = initial_offset
+
+      result = nil
+      loop do
+        unless File.exist?(log_file) && File.size?(log_file)
+          sleep(0.2)
+          next
+        end
+
+        size = File.size(log_file)
+        output = File.read(log_file, size-offset, offset)
+
+        if /AXError: Could not auto-register for pid status change/.match(output)
+          if /kAXErrorServerNotFound/.match(output)
+            self.log_instruments_error('Accessibility is not enabled on device/simulator, please enable it.')
+          end
+          raise RunLoop::TimeoutError.new('AXError: Could not auto-register for pid status change')
+        end
+
+        if /Automation Instrument ran into an exception/.match(output)
+          raise RunLoop::TimeoutError.new('Exception while running script')
+        end
+
+        if /FBSOpenApplicationErrorDomain error/.match(output)
+          msg = "Instruments failed to launch app: 'FBSOpenApplicationErrorDomain error 8"
+          if RunLoop::Environment.debug?
+            self.log_instruments_error(msg)
+          end
+          raise RunLoop::TimeoutError.new(msg)
+        end
+
+        if /Error: Script threw an uncaught JavaScript error: unknown JavaScript exception/.match(output)
+          msg = "Instruments failed to launch: because of an unknown JavaScript exception"
+          if RunLoop::Environment.debug?
+            self.log_instruments_error(msg)
+          end
+          raise RunLoop::TimeoutError.new(msg)
+        end
+
+        index_if_found = output.index(START_DELIMITER)
+        if debug_read
+          puts output.gsub('*', '')
+          puts "Size #{size}"
+          puts "offset #{offset}"
+          puts "index_of #{START_DELIMITER}: #{index_if_found}"
+        end
+
+        if index_if_found
+
+          offset = offset + index_if_found
+          rest = output[index_if_found+START_DELIMITER.size..output.length]
+          index_of_json = rest.index("}#{END_DELIMITER}")
+
+          if index_of_json.nil?
+            #Wait for rest of json
+            sleep(0.1)
+            next
+          end
+
+          json = rest[0..index_of_json]
+
+
+          if debug_read
+            puts "Index #{index_if_found}, Size: #{size} Offset #{offset}"
+
+            puts ("parse #{json}")
+          end
+
+          offset = offset + json.size
+          parsed_result = JSON.parse(json)
+          if debug_read
+            p parsed_result
+          end
+          json_index_if_present = parsed_result[search_for_property]
+          if json_index_if_present && json_index_if_present == expected_index
+            result = parsed_result
+            break
+          end
+        else
+          sleep(0.1)
+        end
+      end
+
+      run_loop[:initial_offset] = offset
+      RunLoop::HostCache.default.write(run_loop) unless RunLoop::Environment.xtc?
+      result
+    end
+
+    def self.automation_template(instruments, candidate=RunLoop::Environment.trace_template)
+      unless candidate && File.exist?(candidate)
+        candidate = default_tracetemplate(instruments)
+      end
+      candidate
+    end
+
+    def self.default_tracetemplate(instruments=RunLoop::Instruments.new)
+
+      templates = instruments.templates
+
+      # xcrun instruments -s templates
+      # Xcode >= 6 will return known, Apple defined tracetemplates as names
+      #  e.g.  Automation, Zombies, Allocations
+      #
+      # Xcode < 6 will return known, Apple defined tracetemplates as paths.
+      #
+      # Xcode 6 Beta versions also return paths, but revert to 'normal'
+      # behavior when GM is released.
+      #
+      # Xcode 7 Beta versions appear to behavior like Xcode 6 Beta versions.
+      template = templates.find { |name| name == 'Automation' }
+      return template if template
+
+      candidate = templates.find do |path|
+        path =~ /\/Automation.tracetemplate/ and path =~ /Xcode/
+      end
+
+      if !candidate.nil?
+        return candidate.tr("\"", '').strip
+      end
+
+      message = ['Expected instruments to report an Automation tracetemplate.',
+                 'Please report this as bug:  https://github.com/calabash/run_loop/issues',
+                 "In the bug report, include the output of:\n",
+                 '$ xcrun xcodebuild -version',
+                 "$ xcrun instruments -s templates\n"]
+      raise message.join("\n")
+    end
+
+    # @deprecated 2.1.0
+    # Replaced with Device.detect_physical_device_on_usb
+    def self.detect_connected_device
+      begin
+        Timeout::timeout(1, RunLoop::TimeoutError) do
+          return `#{File.join(SCRIPTS_PATH, 'udidetect')}`.chomp
+        end
+      rescue RunLoop::TimeoutError => _
+        `killall udidetect &> /dev/null`
+      end
+      nil
+    end
+
+    # @deprecated 2.1.0
+    # @!visibility private
+    # Are we targeting a simulator?
+    #
+    # @note  The behavior of this method is different than the corresponding
+    #   method in Calabash::Cucumber::Launcher method.  If
+    #   `:device_target => {nil | ''}`, then the calabash-ios method returns
+    #   _false_.  I am basing run-loop's behavior off the behavior in
+    #   `self.udid_and_bundle_for_launcher`
+    #
+    # @see {Core::RunLoop.udid_and_bundle_for_launcher}
+    #
+    # @todo sim_control argument is no longer necessary and can be removed.
+    def self.simulator_target?(run_options, sim_control=nil)
+      # TODO Enable deprecation warning
+      # RunLoop.deprecated("2.1.0", "No replacement")
+      value = run_options[:device_target]
+
+      # Match the behavior of udid_and_bundle_for_launcher.
+      return true if value.nil? or value == ''
+
+      # 5.1 <= Xcode < 7.0
+      return true if value.downcase.include?('simulator')
+
+      # Not a physical device.
+      return false if value[DEVICE_UDID_REGEX, 0] != nil
+
+      # Check for named simulators and Xcode >= 7.0 simulators.
+      simctl = run_options[:sim_control] || run_options[:simctl] || RunLoop::Simctl.new
+      xcode = run_options[:xcode] || RunLoop::Xcode.new
+      simulator = simctl.simulators.find do |sim|
+        [
+          sim.instruments_identifier(xcode) == value,
+          sim.udid == value,
+          sim.name == value
+        ].any?
+      end
+      !simulator.nil?
+    end
+
+    # @!visibility private
+    # @deprecated 2.1.0
+    #
+    # Do not call this method.
+    def self.udid_and_bundle_for_launcher(device_target, options, simctl=RunLoop::Simctl.new)
+      RunLoop.deprecated("2.1.0", "No replacement")
+      xcode = RunLoop::Xcode.new
+
+      bundle_dir_or_bundle_id = options[:app] || RunLoop::Environment.bundle_id || RunLoop::Environment.path_to_app_bundle
+
+      unless bundle_dir_or_bundle_id
+        raise 'key :app or environment variable APP_BUNDLE_PATH, BUNDLE_ID or APP must be specified as path to app bundle (simulator) or bundle id (device)'
+      end
+
+      if device_target.nil? || device_target.empty? || device_target == 'simulator'
+        device_target = self.default_simulator(xcode)
+      end
+      udid = device_target
+
+      unless self.simulator_target?(options)
+        bundle_dir_or_bundle_id = options[:bundle_id] if options[:bundle_id]
+      end
+      return udid, bundle_dir_or_bundle_id
+    end
+
+    # @deprecated 1.0.5
+    def self.ensure_instruments_not_running!
+      RunLoop::Instruments.new.kill_instruments
+    end
+
+    def self.instruments_running?
+      RunLoop::Instruments.new.instruments_running?
+    end
+
+    # @deprecated 1.0.5
+    def self.instruments_pids
+      RunLoop::Instruments.new.instruments_pids
+    end
+
+    # @deprecated 1.0.0 replaced with Xctools#version
+    def self.xcode_version(xcode=RunLoop::Xcode.new)
+      xcode.version
+    end
+
+    # @deprecated since 1.0.0
+    # still used extensively in calabash-ios launcher
+    def self.above_or_eql_version?(target_version, xcode_version)
+      if target_version.is_a?(RunLoop::Version)
+        target = target_version
+      else
+        target = RunLoop::Version.new(target_version)
+      end
+
+      if xcode_version.is_a?(RunLoop::Version)
+        xcode = xcode_version
+      else
+        xcode = RunLoop::Version.new(xcode_version)
+      end
+      target >= xcode
+    end
+
+    # @deprecated 1.0.5
+    def self.pids_for_run_loop(run_loop, &block)
+      RunLoop::Instruments.new.instruments_pids(&block)
+    end
+
+    private
+
+    # @!visibility private
+    #
+    # @param [Hash] options The launch options passed to .run_with_options
+    def self.prepare(run_options)
+      RunLoop::DotDir.rotate_result_directories
+      RunLoop::Instruments.rotate_cache_directories
+      true
+    end
+
+    # @!visibility private
+    #
+    # @param [RunLoop::Device] device The device under test.
+    # @param [RunLoop::Xcode] xcode The active Xcode
+    def self.default_uia_strategy(device, xcode)
+      if xcode.version_gte_7?
+        :host
+      elsif device.physical_device? && device.version >= RunLoop::Version.new("8.0")
+        :host
+      else
+        :preferences
+      end
+    end
+
+    # @!visibility private
+    #
+    # @param [Hash] options The launch options passed to .run_with_options
+    # @param [RunLoop::Device] device The device under test.
+    # @param [RunLoop::Xcode] xcode The active Xcode.
+    def self.detect_uia_strategy(options, device, xcode)
+      strategy = options[:uia_strategy] || self.default_uia_strategy(device, xcode)
+
+      if ![:host, :preferences, :shared_element].include?(strategy)
+        raise ArgumentError,
+              "Invalid strategy: expected '#{strategy}' to be :host, :preferences, or :shared_element"
+      end
+      strategy
+    end
+
+    # @!visibility private
+    #
+    # There is an unnatural relationship between the :script and the
+    # :uia_strategy keys.
+    #
+    # @param [Hash] options The launch options passed to .run_with_options
+    # @param [RunLoop::Device] device The device under test.
+    # @param [RunLoop::Xcode] xcode The active Xcode.
+    #
+    # @return [Hash] with two keys: :script and :uia_strategy
+    def self.detect_instruments_script_and_strategy(options, device, xcode)
+      strategy = options[:uia_strategy]
+      script = options[:script]
+
+      if script
+        script = self.expect_instruments_script(script)
+        if !strategy
+          strategy = :host
+        end
+      else
+        if strategy
+          script = self.instruments_script_for_uia_strategy(strategy)
+        else
+          if options[:calabash_lite]
+            strategy = :host
+            script = self.instruments_script_for_uia_strategy(strategy)
+          else
+            strategy = self.detect_uia_strategy(options, device, xcode)
+            script = self.instruments_script_for_uia_strategy(strategy)
+          end
+        end
+      end
+
+      {
+        :script => script,
+        :strategy => strategy
+      }
+    end
+
+    # @!visibility private
+    #
+    # UIAutomation buffers log output in some very strange ways.  RunLoop
+    # attempts to work around this buffering by forcing characters onto the
+    # UIALogger buffer.  Once the buffer is full, UIAutomation will dump its
+    # contents.  It is essential that the communication between UIAutomation
+    # and RunLoop be synchronized.
+    #
+    # Casual users should never set the :flush_uia_logs key; they should use the
+    # defaults.
+    #
+    # :no_flush is supported (for now) as alternative key.
+    #
+    # @param [Hash] options The launch options passed to .run_with_options
+    def self.detect_flush_uia_log_option(options)
+      if options.has_key?(:no_flush)
+        # Confusing.
+        # :no_flush == false means, flush the logs.
+        # :no_flush == true means, don't flush the logs.
+        return !options[:no_flush]
+      end
+
+      return options.fetch(:flush_uia_logs, true)
+    end
+
+    # @!visibility private
+    #
+    # @param [Hash] options The launch options passed to .run_with_options
+    def self.detect_reset_options(options)
+      return options[:reset] if options.has_key?(:reset)
+
+      return options[:reset_app_sandbox] if options.has_key?(:reset_app_sandbox)
+
+      RunLoop::Environment.reset_between_scenarios?
+    end
+
+    # Prepares the simulator for running.
+    #
+    # 1. enabling accessibility and software keyboard
+    # 2. installing / uninstalling apps
+    #
+    # TODO: move to CoreSimulator?
+    def self.prepare_simulator(app, device, xcode, simctl, reset_options)
+
+      # Validate the architecture.
+      self.expect_simulator_compatible_arch(device, app)
+
+      # Quits the simulator.
+      core_sim = RunLoop::CoreSimulator.new(device, app, :xcode => xcode)
+
+      # Calabash 0.x can only reset the app sandbox (true/false).
+      # Calabash 2.x has advanced reset options.
+      if reset_options
+        core_sim.reset_app_sandbox
+      end
+
+      # Will quit the simulator if it is running.
+      # @todo fix accessibility_enabled? so we don't have to quit the sim
+      # SimControl#accessibility_enabled? is always false during Core#prepare_simulator
+      # https://github.com/calabash/run_loop/issues/167
+      simctl.ensure_accessibility(device)
+
+      # Will quit the simulator if it is running.
+      # @todo fix software_keyboard_enabled? so we don't have to quit the sim
+      # SimControl#software_keyboard_enabled? is always false during Core#prepare_simulator
+      # https://github.com/calabash/run_loop/issues/168
+      simctl.ensure_software_keyboard(device)
+
+      # Launches the simulator if the app is not installed.
+      core_sim.install
+
+      # If CoreSimulator has already launched the simulator, it will not launch it again.
+      core_sim.launch_simulator
+    end
+
+    # @!visibility private
+    # Raise an error if the application binary is not compatible with the
+    # target simulator.
+    #
+    # @param [RunLoop::Device] device The device to install on.
+    # @param [RunLoop::App] app The app to install.
+    #
+    # @raise [RunLoop::IncompatibleArchitecture] Raises an error if the
+    #  application binary is not compatible with the target simulator.
+    def self.expect_simulator_compatible_arch(device, app)
+      lipo = RunLoop::Lipo.new(app.path)
+      lipo.expect_compatible_arch(device)
+
+      RunLoop.log_debug("Simulator instruction set '#{device.instruction_set}' is compatible with '#{lipo.info}'")
+    end
+
+    # @!visibility private
+    def self.expect_instruments_script(script)
+      if script.is_a?(String)
+        unless File.exist?(script)
+          raise %Q[Expected instruments JavaScript file at path:
+
+#{script}
+
+Check the :script key in your launch options.]
+        end
+        script
+      elsif script.is_a?(Symbol)
+        path = self.script_for_key(script)
+        if !path
+          raise %Q[Expected :#{script} to be one of:
+
+#{Core::SCRIPTS.keys.map { |key| ":#{key}" }.join("\n")}
+
+Check the :script key in your launch options.]
+        end
+        path
+      else
+        raise %Q[Expected '#{script}' to be a Symbol or a String.
+
+Check the :script key in your launch options.]
+      end
+    end
+
+    # @!visibility private
+    def self.instruments_script_for_uia_strategy(uia_strategy)
+      case uia_strategy
+      when :preferences
+        self.script_for_key(:run_loop_fast_uia)
+      when :host
+        self.script_for_key(:run_loop_host)
+      when :shared_element
+        self.script_for_key(:run_loop_shared_element)
+      else
+        self.script_for_key(:run_loop_basic)
+      end
+    end
+  end
+end
+