run_loop_tcc 2.1.3

data/lib/run_loop/physical_device/life_cycle.rb

@@ -0,0 +1,268 @@
+module RunLoop
+  # @!visibility private
+  module PhysicalDevice
+
+    # Raised when installation fails.
+    class InstallError < RuntimeError; end
+
+    # Raised when uninstall fails.
+    class UninstallError < RuntimeError; end
+
+    # Raised when tool cannot perform task.
+    class NotImplementedError < StandardError; end
+
+    # Controls the behavior of various life cycle commands.
+    #
+    # You can override these values if they do not work in your environment.
+    #
+    # For cucumber users, the best place to override would be in your
+    # features/support/env.rb.
+    #
+    # For example:
+    #
+    # RunLoop::PhysicalDevice::LifeCycle::DEFAULT_OPTIONS[:timeout] = 60
+    DEFAULT_OPTIONS = {
+      :install_timeout => RunLoop::Environment.ci? ? 120 : 30
+    }
+
+    # @!visibility private
+    class LifeCycle
+
+      require "run_loop/abstract"
+      include RunLoop::Abstract
+
+      require "run_loop/shell"
+      include RunLoop::Shell
+
+      attr_reader :device
+
+      # Create a new instance.
+      #
+      # @param [RunLoop::Device] device A physical device.
+      # @raise [ArgumentError] If device is a simulator.
+      def initialize(device)
+        if !device.physical_device?
+          raise ArgumentError, %Q[Device:
+
+#{device}
+
+must be a physical device.]
+        end
+        @device = device
+      end
+
+      # Is the tool installed?
+      def self.tool_is_installed?
+        raise RunLoop::Abstract::AbstractMethodError,
+          "Subclass must implement '.tool_is_installed?'"
+      end
+
+      # Path to tool.
+      def self.executable_path
+        raise RunLoop::Abstract::AbstractMethodError,
+          "Subclass must implement '.executable_path'"
+      end
+
+      # Is the app installed?
+      #
+      # @param [String] bundle_id The CFBundleIdentifier of an app.
+      # @return [Boolean] true or false
+      def app_installed?(bundle_id)
+        abstract_method!
+      end
+
+      # Install the app or ipa.
+      #
+      # If the app is already installed, it will be reinstalled from disk;
+      # no version check is performed.
+      #
+      # App data is never preserved.  If you want to preserve the app data,
+      # call `ensure_newest_installed`.
+      #
+      # Possible return values:
+      #
+      # * :reinstalled => app was installed, but app data was not preserved.
+      # * :installed => app was not installed.
+      #
+      # @param [RunLoop::Ipa, RunLoop::App] app_or_ipa The ipa to install.
+      #   The caller is responsible for validating the ipa for the device by
+      #   checking that the codesign and instruction set is correct.
+      #
+      # @raise [InstallError] If app was not installed.
+      #
+      # @return [Symbol] A keyword describing the action that was performed.
+      def install_app(app_or_ipa)
+        abstract_method!
+      end
+
+      # Uninstall the app with bundle_id.
+      #
+      # App data is never preserved.  If you want to install a new version of
+      # an app and preserve app data (upgrade testing), call
+      # `ensure_newest_installed`.
+      #
+      # Possible return values:
+      #
+      # * :nothing => app was not installed
+      # * :uninstall => app was uninstalled
+      #
+      # @param [String] bundle_id The CFBundleIdentifier of an app.
+      #
+      # @raise [UninstallError] If the app cannot be uninstalled, usually
+      #   because it is a system app.
+      #
+      # @return [Symbol] A keyword that describes what action was performed.
+      def uninstall_app(bundle_id)
+        abstract_method!
+      end
+
+      # Ensures the app is installed and ensures that app is not stale by
+      # asking if the version of installed app is different than the version
+      # of the app or ipa on disk.
+      #
+      # The concrete implementation needs to check the CFBundleVersion and
+      # the CFBundleShortVersionString.  If either are different, then the
+      # app should be reinstalled.
+      #
+      # If possible, the app data should be preserved across reinstallation.
+      #
+      # Possible return values:
+      #
+      # * :nothing => app was already installed and versions matched.
+      # * :upgraded => app was stale; newer version from disk was installed and
+      #                app data was preserved.
+      # * :reinstalled => app was stale; newer version from disk was installed,
+      #                   but app data was not preserved.
+      # * :installed => app was not installed.
+      #
+      # @param [RunLoop::Ipa, RunLoop::App] app_or_ipa The ipa to install.
+      #   The caller is responsible for validating the ipa for the device by
+      #   checking that the codesign and instruction set is correct.
+      #
+      # @raise [InstallError] If the app could not be installed.
+      # @raise [UninstallError] If the app could not be uninstalled.
+      #
+      # @return [Symbol] A keyword that describes the action that was taken.
+      def ensure_newest_installed(app_or_ipa)
+        abstract_method!
+      end
+
+      # Is the app on disk the same as the installed app?
+      #
+      # The concrete implementation needs to check the CFBundleVersion and
+      # the CFBundleShortVersionString. If either are different, then this
+      # method returns false.
+      #
+      # @param [RunLoop::Ipa, RunLoop::App] app_or_ipa The ipa to install.
+      #   The caller is responsible for validating the ipa for the device by
+      #   checking that the codesign and instruction set is correct.
+      #
+      # @raise [RuntimeError] If app is not already installed.
+      def installed_app_same_as?(app_or_ipa)
+        abstract_method!
+      end
+
+      # Returns true if this tool can reset an app's sandbox without
+      # uninstalling the app.
+      def can_reset_app_sandbox?
+        abstract_method!
+      end
+
+      # Clear the app sandbox.
+      #
+      # This method will never uninstall the app.  If the concrete
+      # implementation cannot reset the app data, this method should raise
+      # a RunLoop::PhysicalDevice::NotImplementedError
+      #
+      # Does not clear Keychain.  Use the Calabash iOS Keychain API.
+      #
+      # @param [String] bundle_id The CFBundleIdentifier of an app.
+      #
+      # @raise [RunLoop::PhysicalDevice::NotImplementedError] If this tool
+      #   cannot reset the app sandbox without unintalling the app.
+      def reset_app_sandbox(bundle_id)
+        abstract_method!
+      end
+
+      # Return the architecture of the device.
+      def architecture
+        abstract_method!
+      end
+
+      # Is the app or ipa compatible with the architecture of the device?
+      def app_has_compatible_architecture?(app_or_ipa)
+        abstract_method!
+      end
+
+      # Return true if the device is an iPhone.
+      def iphone?
+        abstract_method!
+      end
+
+      # Return false if the device is an iPad.
+      def ipad?
+        abstract_method!
+      end
+
+      # Return the model of the device.
+      def model
+        abstract_method!
+      end
+
+      # Sideload data into the app's sandbox.
+      #
+      # These directories exist in the application sandbox.
+      #
+      # * sandbox/Documents
+      # * sandbox/Library
+      # * sandbox/Library/Preferences
+      # * sandbox/tmp
+      #
+      # Behavior TBD.
+      def sideload(data)
+        raise NotImplementedError,
+          "The behavior of the sideload method has not been determined"
+      end
+
+      # Removes a file or directory from the app sandbox.
+      #
+      # Behavior TBD.
+      def remove_from_sandbox(path)
+        raise NotImplementedError,
+          "The behavior of the remove_from_sandbox method has not been determined"
+      end
+
+      # @!visibility private
+      def expect_app_or_ipa(app_or_ipa)
+        if ![is_app?(app_or_ipa), is_ipa?(app_or_ipa)].any?
+          if app_or_ipa.nil?
+            object = "nil"
+          elsif app_or_ipa == ""
+            object = "<empty string>"
+          else
+            object = app_or_ipa
+          end
+
+          raise ArgumentError, %Q[Expected:
+
+#{object}
+
+to be a RunLoop::App or a RunLoop::Ipa.]
+        end
+
+        true
+      end
+
+      # @!visibility private
+      def is_app?(app_or_ipa)
+        app_or_ipa.is_a?(RunLoop::App)
+      end
+
+      # @!visibility private
+      def is_ipa?(app_or_ipa)
+        app_or_ipa.is_a?(RunLoop::Ipa)
+      end
+    end
+  end
+end
+

data/lib/run_loop/plist_buddy.rb

@@ -0,0 +1,189 @@
+module RunLoop
+  # A class for reading and writing property list values.
+  #
+  # Why not use CFPropertyList?  Because it is super wonky.  Among its other
+  # faults, it matches Boolean to a string type with 'true/false' values which
+  # is problematic for our purposes.
+  class PlistBuddy
+
+    # Reads key from file and returns the result.
+    # @param [String] key the key to inspect (may not be nil or empty)
+    # @param [String] file the plist to read
+    # @param [Hash] opts options for controlling execution
+    # @option opts [Boolean] :verbose (false) controls log level
+    # @return [String] the value of the key
+    # @raise [ArgumentError] if nil or empty key
+    def plist_read(key, file, opts={})
+      if key.nil? or key.length == 0
+        raise(ArgumentError, "key '#{key}' must not be nil or empty")
+      end
+      cmd = build_plist_cmd(:print, {:key => key}, file)
+      res = execute_plist_cmd(cmd, opts)
+      if res == "Print: Entry, \":#{key}\", Does Not Exist"
+        nil
+      else
+        res
+      end
+    end
+
+    # Checks if the key exists in plist.
+    # @param [String] key the key to inspect (may not be nil or empty)
+    # @param [String] file the plist to read
+    # @param [Hash] opts options for controlling execution
+    # @option opts [Boolean] :verbose (false) controls log level
+    # @return [Boolean] true if the key exists in plist file
+    def plist_key_exists?(key, file, opts={})
+      plist_read(key, file, opts) != nil
+    end
+
+    # Replaces or creates the value of key in the file.
+    #
+    # @param [String] key the key to set (may not be nil or empty)
+    # @param [String] type the plist type (used only when adding a value)
+    # @param [String] value the new value
+    # @param [String] file the plist to read
+    # @param [Hash] opts options for controlling execution
+    # @option opts [Boolean] :verbose (false) controls log level
+    # @return [Boolean] true if the operation was successful
+    # @raise [ArgumentError] if nil or empty key
+    def plist_set(key, type, value, file, opts={})
+      default_opts = {:verbose => false}
+      merged = default_opts.merge(opts)
+
+      if key.nil? or key.length == 0
+        raise(ArgumentError, "key '#{key}' must not be nil or empty")
+      end
+
+      cmd_args = {:key => key,
+                  :type => type,
+                  :value => value}
+
+      if plist_key_exists?(key, file, merged)
+        cmd = build_plist_cmd(:set, cmd_args, file)
+      else
+        cmd = build_plist_cmd(:add, cmd_args, file)
+      end
+
+      res = execute_plist_cmd(cmd, merged)
+      res == ''
+    end
+
+    # Creates an new empty plist at `path`.
+    #
+    # Is not responsible for creating directories or ensuring write permissions.
+    #
+    # @param [String] path Where to create the new plist.
+    def create_plist(path)
+      File.open(path, 'w') do |file|
+        file.puts "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
+        file.puts "<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">"
+        file.puts "<plist version=\"1.0\">"
+        file.puts '<dict>'
+        file.puts '</dict>'
+        file.puts '</plist>'
+      end
+      path
+    end
+
+    private
+
+    # returns the path to the PlistBuddy executable
+    # @return [String] path to PlistBuddy
+    def plist_buddy
+      '/usr/libexec/PlistBuddy'
+    end
+
+    # Executes cmd as a shell command and returns the result.
+    #
+    # @param [String] cmd shell command to execute
+    # @param [Hash] opts options for controlling execution
+    # @option opts [Boolean] :verbose (false) controls log level
+    # @return [Boolean,String] `true` if command was successful.  If :print'ing
+    #  the result, the value of the key.  If there is an error, the output of
+    #  stderr.
+    def execute_plist_cmd(cmd, opts={})
+      default_opts = {:verbose => false}
+      merged = default_opts.merge(opts)
+
+      puts cmd if merged[:verbose]
+
+      res = nil
+      # noinspection RubyUnusedLocalVariable
+      Open3.popen3(cmd) do |stdin, stdout, stderr, wait_thr|
+        err = stderr.read
+        std = stdout.read
+        if not err.nil? and err != ''
+          res = err.chomp
+        else
+          res = std.chomp
+        end
+      end
+      res
+    end
+
+    # Composes a PlistBuddy command that can be executed as a shell command.
+    #
+    # @param [Symbol] type should be one of [:print, :set, :add]
+    #
+    # @param [Hash] args_hash arguments used to construct plist command
+    # @option args_hash [String] :key (required) the plist key
+    # @option args_hash [String] :value (required for :set and :add) the new value
+    # @option args_hash [String] :type (required for :add) the new type of the value
+    #
+    # @param [String] file the plist file to interact with (must exist)
+    #
+    # @raise [RuntimeError] if file does not exist
+    # @raise [ArgumentError] when invalid type is passed
+    # @raise [ArgumentError] when args_hash does not include required key/value pairs
+    #
+    # @return [String] a shell-ready PlistBuddy command
+    def build_plist_cmd(type, args_hash, file)
+
+      unless File.exist?(File.expand_path(file))
+        raise(RuntimeError, "plist '#{file}' does not exist - could not read")
+      end
+
+      case type
+        when :add
+          value_type = args_hash[:type]
+          unless value_type
+            raise(ArgumentError, ':value_type is a required key for :add command')
+          end
+          allowed_value_types = ['string', 'bool', 'real', 'integer']
+          unless allowed_value_types.include?(value_type)
+            raise(ArgumentError, "expected '#{value_type}' to be one of '#{allowed_value_types}'")
+          end
+          value = args_hash[:value]
+          unless value
+            raise(ArgumentError, ':value is a required key for :add command')
+          end
+          key = args_hash[:key]
+          unless key
+            raise(ArgumentError, ':key is a required key for :add command')
+          end
+          cmd_part = "\"Add :#{key} #{value_type} #{value}\""
+        when :print
+          key = args_hash[:key]
+          unless key
+            raise(ArgumentError, ':key is a required key for :print command')
+          end
+          cmd_part = "\"Print :#{key}\""
+        when :set
+          value = args_hash[:value]
+          unless value
+            raise(ArgumentError, ':value is a required key for :set command')
+          end
+          key = args_hash[:key]
+          unless key
+            raise(ArgumentError, ':key is a required key for :set command')
+          end
+          cmd_part = "\"Set :#{key} #{value}\""
+        else
+          cmds = [:add, :print, :set]
+          raise(ArgumentError, "expected '#{type}' to be one of '#{cmds}'")
+      end
+
+      "#{plist_buddy} -c #{cmd_part} \"#{file}\""
+    end
+  end
+end

data/lib/run_loop/process_terminator.rb

@@ -0,0 +1,128 @@
+module RunLoop
+
+  # A class for terminating processes and waiting for them to die.
+  class ProcessTerminator
+
+    # @!attribute [r] pid
+    # The process id of the process.
+    # @return [Integer] The pid.
+    attr_reader :pid
+
+    # @!attribute [r] kill_signal
+    # The kill signal to send to the process. Can be a Unix signal name or an
+    #   Integer.
+    # @return [Integer, String] The kill signal.
+    attr_reader :kill_signal
+
+    # @!attribute [r] display_name
+    # The process name to use log messages and exceptions.  Not used to find
+    #   or otherwise interact with the process.
+    # @return [String] The display name.
+    attr_reader :display_name
+
+    # @!attribute [r] options
+    # Options to control the behavior of `kill_process`.
+    # @return [Hash] A hash of options.
+    attr_reader :options
+
+    # Create a new process terminator.
+    #
+    # @param[String,Integer] pid The process pid.
+    # @param[String, Integer] kill_signal The kill signal to send to the process.
+    # @param[String] display_name The name of the process to kill. Used only
+    #  in log messages and exceptions.
+    # @option options [Float] :timeout (2.0) How long to wait for the process to
+    #  terminate.
+    # @option options [Float] :interval (0.1) The polling interval.
+    # @option options [Boolean] :raise_on_no_terminate (false) Should an error
+    #  be raised if process does not terminate.
+    def initialize(pid, kill_signal, display_name, options={})
+      @options = DEFAULT_OPTIONS.merge(options)
+      @pid = pid.to_i
+      @kill_signal = kill_signal
+      @display_name = display_name
+    end
+
+    # Try to kill the process identified by `pid`.
+    #
+    # After sending  `kill_signal` to `pid`, wait for the process to terminate.
+    #
+    # @return [Boolean] Returns true if the process was terminated or is no
+    #  longer alive.
+    # @raise [SignalException] Raised on an unhandled `Process.kill` exception.
+    #   Errno:ESRCH and Errno:EPERM are _handled_ exceptions; all others will
+    #   be raised.
+    def kill_process
+      return true unless process_alive?
+
+      begin
+        RunLoop.log_debug("Sending '#{kill_signal}' to #{display_name} process '#{pid}'")
+        Process.kill(kill_signal, pid.to_i)
+        # Don't wait.
+        # We might not own this process and a WNOHANG would be a nop.
+        # Process.wait(pid, Process::WNOHANG)
+      rescue Errno::ESRCH
+        RunLoop.log_debug("Process with pid '#{pid}' does not exist; nothing to do.")
+        # Return early; there is no need to wait if the process does not exist.
+        return true
+      rescue Errno::EPERM
+        RunLoop.log_debug("Cannot kill process '#{pid}' with '#{kill_signal}'; not a child of this process")
+      rescue SignalException => e
+        raise e.message
+      end
+      RunLoop.log_debug("Waiting for #{display_name} with pid '#{pid}' to terminate")
+      wait_for_process_to_terminate
+    end
+
+    # Is the process `pid` alive?
+    # @return [Boolean] Returns true if the process is still alive.
+    def process_alive?
+      begin
+        Process.kill(0, pid.to_i)
+        true
+      rescue Errno::ESRCH
+        false
+      rescue Errno::EPERM
+        true
+      end
+    end
+
+    private
+
+    # @!visibility private
+    # The default options for waiting on a process to terminate.
+    DEFAULT_OPTIONS =
+          {
+                :timeout => 2.0,
+                :interval => 0.1,
+                :raise_on_no_terminate => false
+          }
+
+    # @!visibility private
+    # The details of the process reported by `ps`.
+    def ps_details
+      `xcrun ps -p #{pid} -o pid,comm | grep #{pid}`.strip
+    end
+
+    # @!visibility private
+    # Wait for the process to terminate by polling.
+    def wait_for_process_to_terminate
+      now = Time.now
+      poll_until = now + options[:timeout]
+      delay = options[:interval]
+      has_terminated = false
+      while Time.now < poll_until
+        has_terminated = !process_alive?
+        break if has_terminated
+        sleep delay
+      end
+
+      RunLoop.log_debug("Waited for #{Time.now - now} seconds for #{display_name} with pid '#{pid}' to terminate")
+
+      if @options[:raise_on_no_terminate] and !has_terminated
+        raise "Waited #{options[:timeout]} seconds for #{display_name} (#{ps_details}) to terminate"
+      end
+      has_terminated
+    end
+  end
+end

data/lib/run_loop/process_waiter.rb

@@ -0,0 +1,117 @@
+module RunLoop
+
+  # A class for waiting on processes.
+  class ProcessWaiter
+
+    attr_reader :process_name
+
+    def initialize(process_name, options={})
+      @options = DEFAULT_OPTIONS.merge(options)
+      @process_name = process_name
+    end
+
+    # Collect a list of Integer pids.
+    # @return [Array<Integer>] An array of integer pids for the `process_name`
+    def pids
+      process_info = `ps x -o pid,comm | grep -v grep | grep '#{process_name}'`
+      process_array = process_info.split("\n")
+      process_array.map { |process| process.split(' ').first.strip.to_i }
+    end
+
+    # Is the `process_name` a running?
+    def running_process?
+      !pids.empty?
+    end
+
+    # Wait for a number of process to start.
+    # @param [Integer] n The number of processes to wait for.
+    # @raise [ArgumentError] If n < 0
+    # @raise [ArgumentError] If n is not an Integer
+    def wait_for_n(n)
+      unless n.is_a?(Integer)
+        raise ArgumentError, "Expected #{n.class} to be #{1.class}"
+      end
+
+      unless n > 0
+        raise ArgumentError, "Expected #{n} to be > 0"
+      end
+
+      return true if pids.count == n
+
+      now = Time.now
+      poll_until = now + @options[:timeout]
+      delay = @options[:interval]
+      there_are_n = false
+      while Time.now < poll_until
+        there_are_n = pids.count == n
+        break if there_are_n
+        sleep delay
+      end
+
+      plural = n > 1 ? "es" : ''
+      RunLoop.log_debug("Waited for #{Time.now - now} seconds for #{n} '#{process_name}' process#{plural} to start.")
+
+      if @options[:raise_on_timeout] and !there_are_n
+        plural = n > 1 ? "es" : ''
+        raise "Waited #{@options[:timeout]} seconds for #{n} '#{process_name}' process#{plural} to start."
+      end
+      there_are_n
+    end
+
+
+    # Wait for `process_name` to start.
+    def wait_for_any
+      return true if running_process?
+
+      now = Time.now
+      poll_until = now + @options[:timeout]
+      delay = @options[:interval]
+      is_alive = false
+      while Time.now < poll_until
+        is_alive = running_process?
+        break if is_alive
+        sleep delay
+      end
+
+      RunLoop.log_debug("Waited for #{Time.now - now} seconds for '#{process_name}' to start.")
+
+      if @options[:raise_on_timeout] and !is_alive
+        raise "Waited #{@options[:timeout]} seconds for '#{process_name}' to start."
+      end
+      is_alive
+    end
+
+    # Wait for all `process_name` to finish.
+    def wait_for_none
+      return true if !running_process?
+
+      now = Time.now
+      poll_until = now + @options[:timeout]
+      delay = @options[:interval]
+      has_terminated = false
+      while Time.now < poll_until
+        has_terminated = !self.running_process?
+        break if has_terminated
+        sleep delay
+      end
+
+      RunLoop.log_debug("Waited for #{Time.now - now} seconds for '#{process_name}' to die.")
+
+      if @options[:raise_on_timeout] and !has_terminated
+        raise "Waited #{@options[:timeout]} seconds for '#{process_name}' to die."
+      end
+      has_terminated
+    end
+
+    private
+
+    # @!visibility private
+    DEFAULT_OPTIONS =
+          {
+                :timeout => 10.0,
+                :interval => 0.1,
+                :raise_on_timeout => false
+          }
+  end
+end
+