rubium-ios 1.0.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bcbe9463c012f64333f88e922ae5389bac71686e
+  data.tar.gz: a70251807d1d63921d943adc60633c402c2cf96b
+SHA512:
+  metadata.gz: e342b39c417d613e69cb7569ef112d221093f8002f6bc150e0ad71a3d435834ef9fa1873089fd52d92772669ea0c4a4ed3a3acdf54b18382a8f45646eb75402b
+  data.tar.gz: 5a9783145a2ae2cdbfcbc8513b39917229d25519b5d81d4101192a7d7ffbb1471dd253722897ebb40589facb6be8417b500f1ae0bd539bff0c3eee4a7fa122a8

data/lib/rubium.rb

@@ -0,0 +1,21 @@
+module Rubium
+  class << self
+    def default_host
+      'localhost'
+    end
+
+    def default_port
+      4723
+    end
+
+    def root_path
+      "/wd/hub"
+    end
+  end
+end
+
+require 'ui_automation'
+require 'ui_automation/element_proxy_methods'
+require 'rubium'
+require 'rubium/driver'
+require 'rubium/capabilities'

data/lib/rubium/capabilities.rb

@@ -0,0 +1,92 @@
+module Rubium
+  module Capabilities
+    class Base
+      LATEST_SDK_VERSION = '7.1'
+      
+      attr_accessor :platform_name
+      attr_accessor :platform_version
+      attr_accessor :device_name
+      attr_accessor :new_command_timeout
+      attr_accessor :app
+      attr_accessor :bundle_id
+      attr_accessor :launch_timeout
+      attr_accessor :auto_accept_alerts
+      attr_accessor :process_arguments
+      
+      def initialize(values = {}, &block)
+        values.merge(default_values).each do |k, v|
+          __send__("#{k}=", v) if respond_to?(k)
+        end
+        
+        yield self if block_given?
+      end
+      
+      def to_hash(additional_keys = {})
+        without_nil_values additional_keys.merge({
+          'platformName' => platform_name,
+          'platformVersion' => platform_version,
+          'deviceName' => device_name,
+          'newCommandTimeout' => new_command_timeout,
+          'app' => app,
+          'bundleId' => bundle_id,
+          'launchTimeout' => launch_timeout,
+          'autoAcceptAlerts' => auto_accept_alerts,
+          'processArguments' => process_arguments,
+          'appium-version' => "1.0"
+        })
+      end
+      
+      private
+      
+      def without_nil_values(hash)
+        hash.delete_if { |k, v| v.nil? }
+      end
+      
+      def default_values
+        {
+          platform_name: 'iOS',
+          platform_version: LATEST_SDK_VERSION,
+          new_command_timeout: 30
+        }
+      end
+    end
+    
+    class Simulator < Base
+      attr_accessor :language
+      attr_accessor :orientation
+      attr_accessor :calendar_format
+      attr_accessor :location_services_enabled
+      attr_accessor :location_services_authorized
+      
+      def to_hash(additional_keys = {})
+        super({
+          'language' => language,
+          'orientation' => orientation,
+          'calendarFormat' => calendar_format,
+          'locationServicesEnabled' => location_services_authorized,
+          'locationServicesAuthorized' => location_services_authorized
+        })
+      end
+      
+      private
+      
+      def default_values
+        super.merge({
+          locale: 'en',
+          orientation: 'PORTRAIT',
+          device_name: 'iPhone Simulator'
+        })
+      end
+    end
+    
+    class Device < Base
+      attr_accessor :udid
+      
+      def to_hash(additional_keys = {})
+        super({
+          'udid' => udid
+        })
+      end
+    end
+  end
+end

data/lib/rubium/driver.rb

@@ -0,0 +1,233 @@
+require 'rubium/session'
+
+module Rubium
+  class Driver
+    attr_accessor :implicit_timeout
+    
+    # The default session timeout, in seconds
+    DEFAULT_SESSION_TIMEOUT = 30
+
+    def initialize(capabilities, host = Rubium.default_host, port = Rubium.default_port)
+      @capabilities = capabilities
+      @host = host
+      @port = port
+      @implicit_timeout = 1
+    end
+    
+    ### @!group Session Management
+
+    # Launches a new Appium session.
+    #
+    # Launching a new Appium session will cause Appium to launch Instruments, which 
+    # in turn will launch your application in the simulator or on your device.
+    #
+    # @param [Numeric] session_timeout the underlying HTTP session timeout, in seconds
+    # @raise [Rubium::Session::ConnectionError] if could not connect to the server.
+    #
+    def launch(session_timeout = DEFAULT_SESSION_TIMEOUT)
+      @session ||= Rubium::Session.new(@host, @port, @capabilities, session_timeout)
+      update_implicit_timeout
+    end
+
+    # Quits the current session, if there is one.
+    #
+    # When you quit a session, Appium will terminate the Instruments process which will 
+    # in turn kill the iOS simulator or remove the app from your device.
+    #
+    def quit
+      @session.terminate if @session
+      @session = nil
+    end
+
+    # Launches a new session, calls the given block, then quits.
+    #
+    # This method lets you treat a session as a transaction, with the given block being
+    # executed after launching then quitting the session when the block returns. 
+    #
+    # Using this method ensures you do not have to explicitly quit the session when you
+    # are finished.
+    #
+    # This method will quit the session after the block has finished executing, even if
+    # the block raises an exception.
+    #
+    # @param [Numeric] session_timeout the underlying HTTP session timeout, in seconds
+    # @raise [RuntimeError] if a session is already running
+    #
+    def with_session(session_timeout = DEFAULT_SESSION_TIMEOUT, &block)
+      raise "Session already running!" if @session
+      launch(session_timeout)
+      begin
+        yield @session if block_given?
+      ensure
+        quit
+      end
+    end
+
+    # Quits any existing session before launching a new one.
+    #
+    def relaunch
+      quit
+      launch
+    end
+
+    ### @!endgroup
+    
+    ### @!group Managing timeouts
+    
+    # Sets the implicit timeout used by the underlying Selenium::WebDriver instance.
+    #
+    # Implicit timeouts are used when trying to find elements on the screen using the
+    # low-level #find and #find_all methods. They do not affect any remotely executed
+    # Javascript and therefore have no affect on code that uses the native Javascript
+    # proxy APIs.
+    #
+    # @param [Numeric] value The new timeout value, in seconds
+    # 
+    def implicit_timeout=(value)
+      @implicit_timeout = value
+      update_implicit_timeout
+    end
+    
+    # Temporarily sets the implicit timeout to the given value and invokes the block.
+    #
+    # After the block has been invoked, the original timeout will be restored.
+    #
+    # @param [Numeric] timeout The temporary timeout, in seconds
+    #
+    def with_implicit_timeout(timeout, &block)
+      update_implicit_timeout(timeout)
+      yield
+      update_implicit_timeout
+    end
+
+    # Returns the native Javascript API implicit timeout
+    # @see UIATarget.timeout()
+    #
+    def native_timeout
+      target.timeout
+    end
+
+    # Sets the native Javascript API implicit timeout
+    # @param [Numeric] new_timeout The new timeout, in seconds
+    # @see UIATarget.setTimeout()
+    # 
+    def native_timeout=(new_timeout)
+      target.set_timeout(new_timeout)
+    end
+
+    # Temporarily sets the native Javascript API implicit timeout by pushing a new
+    # timeout on to the timeout stack, calling the given block and then popping the
+    # timeout off the stack.
+    #
+    # @param [Numeric] value The temporary timeout, in seconds
+    # @see UIATarget.pushTimeout(), UIATarget.popTimeout()
+    #
+    def with_native_timeout(value, &block)
+      target.push_timeout(value)
+      yield if block_given?
+      target.pop_timeout
+    end
+    
+    class TimeoutError < RuntimeError; end
+    
+    # Performs an explicit wait until the given block returns true.
+    #
+    # You can use this method to wait for an explicit condition to occur
+    # before continuing.
+    #
+    # @example
+    #     driver.wait_until { something_happened }
+    # 
+    # @param [Numeric] timeout The explicit wait timeout, in seconds
+    # @param [Numeric] interval The interval to wait between retries.
+    # @yieldreturn [Boolean] The block will be repeatedly called up to the timeout until it returns true.
+    # @raise [Rubium::Driver::TimeoutError] if the wait times out
+    #
+    def wait_until(timeout: 1, interval: 0.2, &block)
+      Selenium::WebDriver::Wait.new(timeout: timeout, interval: interval).until(&block)
+    rescue Selenium::WebDriver::Error::TimeOutError => e
+      raise TimeoutError.new(e.message)
+    end
+
+    ### @!endgroup
+
+    def find(xpath)
+      element_proxy_for driver.find_element(:xpath, xpath)
+    rescue Selenium::WebDriver::Error::NoSuchElementError => e
+      UIAutomation::NoSuchElement.new
+    end
+
+    def find_all(xpath)
+      driver.find_elements(:xpath, xpath)
+    end
+
+    def capture_screenshot(output_file, format = :png)
+      File.open(output_file, 'wb') { |io| io.write driver.screenshot_as(format) }
+    end
+    
+    ### @!group Javascript Proxy Methods
+    
+    # Returns a proxy to the local target (UIATarget).
+    #
+    # This method is the main entry point into the UIAutomation Javascript proxy API.
+    # The local target is the root object in the UIAutomation object graph.
+    #
+    # @return [UIAutomation::Target] A proxy to the local target (UIATarget.localTarget())
+    #
+    def target
+      @target ||= UIAutomation::Target.local_target(self)
+    end
+
+    # Returns a proxy to the native UIAutomation logger.
+    #
+    # @return [UIAutomation::Logger] 
+    def logger
+      @logger ||= UIAutomation::Logger.logger(self)
+    end
+    
+    # Executes a string of Javascript within the Instruments process.
+    #
+    # @param [String] script the Javascript to be executed.
+    # @raise [Selenium::WebDriver::Error::JavascriptError] if the evaluated Javascript errors.
+    # @note This method will always return immediately in the case of an error, regardless of# any implicit or native timeout set. If you need to execute some Javascript until it is  successful, you should consider using an explicit wait.
+    #
+    def execute_script(script)
+      driver.execute_script(script)
+    end
+    alias :execute :execute_script
+
+    ### @!endgroup
+
+    private
+
+    def update_implicit_timeout(value = implicit_timeout)
+      driver.manage.timeouts.implicit_wait = value if @session
+    end
+    
+    def driver
+      raise "You must call #launch to start a session first!" unless @session
+      @session.driver
+    end
+
+    ELEMENT_PROXY_MAPPING = {
+      'UIAKeyboard'         => UIAutomation::Keyboard,
+      'UIATabBar'           => UIAutomation::TabBar,
+      'UIATableView'        => UIAutomation::TableView,
+      'UIATextField'        => UIAutomation::TextField,
+      'UIASecureTextField'  => UIAutomation::TextField,
+      'UIASearchBar'        => UIAutomation::TextField,
+      'UIAWindow'           => UIAutomation::Window,
+      'UIANavigationBar'    => UIAutomation::NavigationBar,
+      'UIAActionSheet'      => UIAutomation::ActionSheet,
+      'UIAActivityView'     => UIAutomation::ActivityView,
+      'UIAPicker'           => UIAutomation::Picker,
+      'UIAPopover'          => UIAutomation::Popover,
+      'UIATextView'         => UIAutomation::TextView
+    }
+
+    def element_proxy_for(element)
+      proxy_klass = ELEMENT_PROXY_MAPPING[element.tag_name] || UIAutomation::Element
+      proxy_klass.from_element_id(driver, element.ref, nil, nil)
+    end
+  end
+end

data/lib/rubium/session.rb

@@ -0,0 +1,26 @@
+require 'selenium-webdriver'
+
+module Rubium
+  class Session
+    attr_reader :driver
+
+    def initialize(host, port, capabilities, timeout = 30)
+      client = Selenium::WebDriver::Remote::Http::Default.new
+      client.timeout = timeout
+
+      @driver = Selenium::WebDriver.for(:remote,
+        desired_capabilities: capabilities.to_hash,
+        url: "http://#{host}:#{port}#{Rubium.root_path}",
+        http_client: client
+      )
+    rescue Errno::ECONNREFUSED
+      raise ConnectionError
+    end
+
+    def terminate
+      @driver.quit rescue nil
+    end
+    
+    class ConnectionError < RuntimeError; end
+  end
+end

data/lib/rubium/version.rb

@@ -0,0 +1,16 @@
+module Rubium
+  module Version
+    MAJOR = 1
+    MINOR = 0
+    TINY  = 0
+
+    def self.to_s
+      version = [MAJOR, MINOR, TINY].join(".")
+      prerelease ? "#{version}.pre" : version
+    end
+    
+    def self.prerelease
+      true
+    end
+  end
+end

data/lib/ui_automation.rb

@@ -0,0 +1,325 @@
+require 'active_support/core_ext/string/inflections'
+require 'json'
+
+module UIAutomation
+  # RemoteProxy acts as a proxy or facade to Appium's ability to remotely execute 
+  # Javascript within the Instruments runtime environment.
+  #
+  # Rather than having to manual build strings of Javascript using the Apple UIAutomation
+  # API and executing them using Rubium::Driver#execute, you can use a RemoteProxy as 
+  # if it was an instance of a Javascript object within the UIAutomation API.
+  #
+  # You can fetch values of properties, perform methods and obtain new proxies to objects
+  # returned by a Javascript method.
+  #
+  # As well as providing explicit APIs for fetching properties and performing methods,
+  # you can also use square-bracket notation for accessing properties and for methods, 
+  # you can just call them on the proxy as if they were Ruby methods. You can perform
+  # any method that is defined in the UIAutomation API and you can also use underscore_case
+  # - it will automatically be converted to `lowerCamelCase`.
+  #
+  # Generally, you wouldn't use this directly but would instead use one of the sub-classes
+  # within the library: the Ruby mirror of the UIAutomation Javascript API is built on top
+  # of this class.
+  #
+  # @example Fetch the 'model' from the local target
+  #     executor = Rubium::Driver.new(capabilities)
+  #     target = UIAutomation::RemoteProxy.new(executor, "UIATarget.localTarget()")
+  #     puts target.model # => 'iOS Simulator'
+  #
+  # @example Set the simulator location on the local target
+  #     target = UIAutomation::RemoteProxy.new(executor, "UIATarget.localTarget()")
+  #     target.set_location(lat: 90.0, lng: -10.0)
+  #
+  # @example Print the rect of the main window
+  #     target = UIAutomation::RemoteProxy.new(executor, "UIATarget.localTarget()")
+  #     application = target.proxy_for(:frontMostApp)
+  #     main_window = application.proxy_for(:mainWindow)
+  #     puts main_window.rect
+  # 
+  class RemoteProxy
+    class << self
+      attr_accessor :debug_on_exception
+    end
+
+    # Creates a new RemoteProxy instance.
+    #
+    # Generally, the executor param will be an instance of `Rubium::Driver` but it 
+    # can be any object that responds to `#execute(string)` and is able to execute the
+    # Javascript remotely using the Selenium web-driver protocol.
+    #
+    # A string of Javascript can be passed as the second parameter and it will automatically be
+    # converted into an instance of `RemoteJavascriptObject`.
+    #
+    # @note Use the factory methods `from_javascript` or `from_element_id` instead
+    # @api private
+    # @param [<Object#execute>] executor An object that can execute remote Javascript
+    # @param [String, RemoteJavascriptObject] remote_object_or_string A Javascript representation of the object to be proxied.
+    #
+    def initialize(executor, remote_object_or_string)
+      @executor = executor
+      @remote_object = remote_object_from(remote_object_or_string)
+    end
+    
+    ### @!group Factory methods
+
+    # Returns a new RemoteProxy instance from a string of Javascript.
+    #
+    # @see #initialize 
+    #
+    def self.from_javascript(executor, javascript, *args)
+      new(executor, RemoteJavascriptObject.new(javascript), *args)
+    end
+
+    # Returns a new RemoteProxy instance from an Appium element ID.
+    #
+    # @note This method uses Appium's own internal element IDs returned from an XPath
+    # query and should not be used directly.
+    #
+    # @see #initialize
+    # @see Rubium::Driver#find
+    #
+    def self.from_element_id(executor, element_id, *args)
+      new(executor, RemoteObjectByElementID.new(element_id), *args)
+    end
+    
+    ### @!endgroup
+    
+    ### @!group Proxy Methods    
+
+    # Returns a new proxy to the Javascript object returned from the method called on the object
+    # represented by self.
+    #
+    # For instance, if the current proxy represents the object `UIATarget.localTarget()` and
+    # you call this method with the method name :frontMostApp, it will return a proxy to the object
+    # represented in the Javascript API by `UIATarget.localTarget().frontMostApp()`.
+    #
+    # @param [Symbol] function_name The Javascript method name that returns the object to be proxied
+    # @param [Array] function_args Any arguments that should be passed to the Javascript method
+    # @param [Class] proxy_klass The type of RemoteProxy class to use (must be a sub-class of RemoteProxy)
+    # @param [Array] proxy_args Any additional arguments required to initialize a specific RemoteProxy sub-class.
+    # @raise `TypeError` if proxy_klass is not a valid sub-class of RemoteProxy
+    # @return [RemoteProxy] default return type
+    # @return [proxy_klass] if specified
+    #
+    def proxy_for(function_name, function_args: [], proxy_klass: RemoteProxy, proxy_args: [])
+      raise TypeError.new("proxy_klass must be a RemoteProxy or sub-class") unless proxy_klass <= RemoteProxy
+      build_proxy(proxy_klass, remote_object.object_for_function(function_name, *function_args), proxy_args)
+    end
+
+    # Performs a function on the current Javascript object and returns the raw value.
+    #
+    # This is useful for any methods that return values like strings, hashes and numbers.
+    #
+    # If you use this to call a method that would normally return another Javascript object
+    # this will simply return an empty hash. Use `#proxy_for` to return  a new proxy to 
+    # another Javascript object instead.
+    #
+    # @param [Symbol] function The name of the Javascript method to call on the object represented by self
+    # @param [args] args A list of arguments to be passed to the Javascript method
+    # @see #method_missing 
+    #
+    def perform(function, *args)
+      @executor.execute_script(remote_object.object_for_function(function, *args).javascript)
+    rescue StandardError => e
+      binding.pry if self.class.debug_on_exception
+      raise "Error performing javascript: #{javascript} (server error: #{e})"
+    end
+
+    # Fetches the value of the named property on the current Javascript object.
+    #
+    # @param [Symbol] property The name of the property to return 
+    # @return [Object] The Ruby equivalent of whatever the Javascript method returns.
+    #
+    def fetch(property)
+      @executor.execute_script(remote_object.object_for_property(property).javascript)
+    rescue StandardError => e
+      binding.pry if self.class.debug_on_exception
+      raise "Error performing javascript: #{javascript} (server error: #{e})"
+    end
+    
+    # Can be used as an alternative to calling #fetch
+    # @see #fetch
+    #
+    def [](property)
+      fetch(property)
+    end
+
+    # @api private
+    def execute_self
+      @executor.execute_script(remote_object.javascript)
+    end
+    
+    ### @!endgroup
+    
+    ### @!group Debugging
+    
+    # Returns the Javascript representation
+    # @return [String]
+    # @see #to_javascript
+    #
+    def to_s
+      to_javascript
+    end
+    
+    
+    def inspect
+      "<RemoteProxy(#{self.class.name}): #{to_javascript}>"
+    end
+
+    # @return [String] the Javascript representation of the proxied object
+    #
+    def to_javascript
+      @remote_object.javascript
+    end
+    alias :javascript :to_javascript
+    
+    ### @!endgroup
+
+    # Represents a remote javascript object using raw javascript, e.g.
+    # to represent the main application, you would initialize this with 
+    # the string 'UIATarget.currentTarget().frontMostApp()'
+    #
+    # @api private
+    #
+    class RemoteJavascriptObject
+      def initialize(javascript)
+        @javascript = javascript
+      end
+
+      def javascript
+        @javascript
+      end
+
+      def to_s
+        javascript
+      end
+
+      def object_for_function(function_name, *args)
+        RemoteJavascriptObject.new("#{javascript}.#{function_name}(#{format_args(args)})")
+      end
+
+      def object_for_subscript(subscript)
+        RemoteJavascriptObject.new("#{javascript}[#{format_arg(subscript)}]")
+      end
+
+      def object_for_property(property_name)
+        RemoteJavascriptObject.new("#{javascript}.#{property_name}")
+      end
+
+      def format_arg(arg)
+        case arg
+          when String, Symbol
+            "'#{arg}'"
+          when Hash, Array
+            arg.to_json
+          else
+            arg
+        end
+      end
+
+      def format_args(args)
+        args.map { |arg| format_arg(arg) }.join(", ")
+      end
+    end
+
+    # Represents a remote javascript object by element ID, where element ID
+    # is the ID of a Selenium::WebDriver::Element returned by one of the built-in
+    # Selenium finder methods.
+    #
+    # This allows us to construct remote proxies to javascript objects that are found
+    # using e.g. an xpath without having to know the actual index path to the object
+    # in the UIAutomation javascript object tree.
+    #
+    # @api private
+    #
+    class RemoteObjectByElementID < RemoteJavascriptObject
+      def initialize(object_id)
+        @object_id = object_id
+      end
+
+      def javascript
+        # this uses internal APIs provided by appium-auto
+        "au.getElement(#{@object_id})"
+      end
+    end
+
+    private
+    
+    def remote_object_from(remote_object_or_string)
+      if remote_object_or_string.is_a?(String)
+        RemoteJavascriptObject.new(remote_object_or_string)
+      elsif remote_object_or_string.is_a?(RemoteJavascriptObject)
+        remote_object_or_string
+      else
+        raise TypeError.new("Remote object must be a RemoteJavascriptObject or String, but was #{remote_object_or_string.class}")
+      end
+    end
+
+    # RemoteProxy lets you call methods that correspond to 
+    # methods in the Javascript API without having to explicitly call perform().
+    #
+    # As with perform(), this should only be used for methods that return values rather 
+    # than other objects.
+    #
+    # You can call methods in the Javascript API using snake_case or lowerCamelCase - all
+    # snake case methods will automatically be transformed into the Javascript lowerCamelCase
+    # equivalent (e.g. text_fields -> textFields).
+    #
+    # @param [Symbol] method will be converted to lowerCamelCase and used as the first argument to #perform
+    # @param [Array] args any arguments will be passed as arguments to the Javascript function
+    # @see #perform
+    #
+    def method_missing(method, *args, &block)
+      perform(method.to_s.camelize(:lower), *args)
+    end
+
+    def window
+      nil
+    end
+    
+    def remote_object
+      @remote_object
+    end
+    
+    def build_proxy(proxy_klass, remote_object, proxy_args)
+      proxy_klass.new(@executor, remote_object, *proxy_args)
+    end
+  end
+
+  class NoSuchElement
+    def method_missing(method, *args, &block)
+      if UIAutomation::Element.method_defined?(method)
+        return nil
+      else
+        warn "Tried to call #{method} on NoSuchElement"
+        super
+      end
+    end
+  end
+  
+  require 'ui_automation/element_definitions'
+  
+  autoload :Element,        'ui_automation/element'
+  autoload :ElementArray,   'ui_automation/element_array'
+  autoload :Application,    'ui_automation/application'
+  autoload :Window,         'ui_automation/window'
+  autoload :TableView,      'ui_automation/table_view'
+  autoload :TabBar,         'ui_automation/tab_bar'
+  autoload :NavigationBar,  'ui_automation/navigation_bar'
+  autoload :TextField,      'ui_automation/text_field'
+  autoload :Keyboard,       'ui_automation/keyboard'
+  autoload :Target,         'ui_automation/target'
+  autoload :Logger,         'ui_automation/logger'
+  autoload :Picker,         'ui_automation/picker'
+  autoload :Popover,        'ui_automation/popover'
+  autoload :TextView,       'ui_automation/text_view'
+  autoload :ActivityView,   'ui_automation/activity_view'
+  autoload :ActionSheet,    'ui_automation/action_sheet'
+  autoload :Alert,          'ui_automation/alert'
+  
+  module Traits
+    autoload :Cancellable,  'ui_automation/traits/cancellable'
+    autoload :TextInput,    'ui_automation/traits/text_input'
+  end
+end