unobtainium 0.2.1 → 0.3.0

data/lib/unobtainium/config.rb

@@ -14,46 +14,54 @@ require 'unobtainium/pathed_hash'
 module Unobtainium
   ##
   # The Config class extends PathedHash by two main pieces of functionality:
+  #
   # - it loads configuration files and turns them into pathed hashes, and
   # - it treats environment variables as overriding anything contained in
   #   the configuration file.
   #
   # For configuration file loading, a named configuration file will be laoaded
-  # if present. A file with the same name but '-local' appended before the
+  # if present. A file with the same name but `-local` appended before the
   # extension will be loaded as well, overriding any values in the original
   # configuration file.
   #
   # For environment variable support, any environment variable named like a
   # path into the configuration hash, but with separators transformed to
   # underscore and all letters capitalized will override values from the
-  # configuration files under that path, i.e. FOO_BAR will override 'foo.bar'.
+  # configuration files under that path, i.e. `FOO_BAR` will override `'foo.bar'`.
   #
   # Environment variables can contain JSON *only*; if the value can be parsed
   # as JSON, it becomes a Hash in the configuration tree. If it cannot be parsed
   # as JSON, it remains a string.
   #
-  # Note: if your configuration file's top-level structure is an array, it will
-  # be returned as a hash with a 'config' key that maps to your file's contents.
+  # **Note:** if your configuration file's top-level structure is an array, it
+  # will be returned as a hash with a 'config' key that maps to your file's
+  # contents.
   # That means that if you are trying to merge a hash with an array config, the
   # result may be unexpected.
   class Config < PathedHash
+    # @api private
     # Very simple YAML parser
     class YAMLParser
       require 'yaml'
 
+      # @return parsed string
       def self.parse(string)
         YAML.load(string)
       end
     end
+    private_constant :YAMLParser
 
+    # @api private
     # Very simple JSON parser
     class JSONParser
       require 'json'
 
+      # @return parsed string
       def self.parse(string)
         JSON.parse(string)
       end
     end
+    private_constant :JSONParser
 
     PathedHash::READ_METHODS.each do |method|
       # Wrap all read functions into something that checks for environment
@@ -89,20 +97,28 @@ module Unobtainium
     end
 
     class << self
+      # @api private
       # Mapping of file name extensions to parser types.
       FILE_TO_PARSER = {
         '.yml'  => YAMLParser,
         '.yaml' => YAMLParser,
         '.json' => JSONParser,
       }.freeze
+      private_constant :FILE_TO_PARSER
 
+      # @api private
       # If the config file contains an Array, this is what they key of the
       # returned Hash will be.
       ARRAY_KEY = 'config'.freeze
+      private_constant :ARRAY_KEY
 
       ##
       # Loads a configuration file with the given file name. The format is
       # detected based on one of the extensions in FILE_TO_PARSER.
+      #
+      # @param path [String] the path of the configuration file to load.
+      # @param resolve_extensions [Boolean] flag whether to resolve configuration
+      #   hash extensions. (see `#resolve_extensions`)
       def load_config(path, resolve_extensions = true)
         # Load base and local configuration files
         base, config = load_base_config(path)
@@ -177,22 +193,25 @@ module Unobtainium
     ##
     # Resolve extensions in configuration hashes. If your hash contains e.g.:
     #
+    # ```yaml
     #   foo:
     #     bar:
     #       some: value
     #     baz:
     #       extends: bar
+    # ```
     #
-    # Then 'foo.baz.some' will equal 'value' after resolving extensions. Note
-    # that :load_config calls this function, so normally you don't need to call
-    # it yourself. You can switch this behaviour off in :load_config.
+    # Then `'foo.baz.some'` will equal `'value'` after resolving extensions. Note
+    # that `:load_config` calls this function, so normally you don't need to call
+    # it yourself. You can switch this behaviour off in `:load_config`.
     #
     # Note that this process has some intended side-effects:
-    # 1) If a hash can't be extended because the base cannot be found, an error
+    #
+    # 1. If a hash can't be extended because the base cannot be found, an error
     #    is raised.
-    # 2) If a hash got successfully extended, the :extends keyword itself is
+    # 1. If a hash got successfully extended, the `extends` keyword itself is
     #    removed from the hash.
-    # 3) In a successfully extended hash, an :base keyword, which contains
+    # 1. In a successfully extended hash, an `base` keyword, which contains
     #    the name of the base. In case of multiple recursive extensions, the
     #    final base is stored here.
     #
@@ -203,6 +222,8 @@ module Unobtainium
       recursive_merge("", "")
     end
 
+    ##
+    # Same as `dup.resolve_extensions!`
     def resolve_extensions
       dup.resolve_extensions!
     end

data/lib/unobtainium/driver.rb

@@ -21,19 +21,29 @@ module Unobtainium
     # Class methods
     class << self
       ##
-      # Create a driver instance with the given arguments
-      def create(*args)
-        new(*args)
+      # Create a driver instance with the given arguments.
+      #
+      # @param label [String, Symbol] Label for the driver to create. Driver
+      #   implementations may accept normalized and alias labels, e.g.
+      #   `:firefox, `:ff`, `:remote`, etc.
+      # @param opts [Hash] Options passed to the driver implementation.
+      def create(label, opts = nil)
+        new(label, opts)
       end
 
       ##
       # Add a new driver implementation. The first parameter is the class
       # itself, the second should be a file path pointing to the file where
-      # the class is defined. You would typically pass __FILE__ for the second
+      # the class is defined. You would typically pass `__FILE__` for the second
       # parameter.
       #
       # Using file names lets us figure out whether the class is a duplicate,
       # or merely a second registration of the same class.
+      #
+      # Driver classes must implement the class methods listed in `DRIVER_METHODS`.
+      #
+      # @param klass (Class) Driver implementation class to register.
+      # @param path (String) Implementation path of the driver class.
       def register_implementation(klass, path)
         # We need to deal with absolute paths only
         fpath = File.absolute_path(path)
@@ -63,41 +73,46 @@ module Unobtainium
       private :new
 
       ##
-      # Ensures arguments are according to expectations.
-      def sanitize_options(*args)
-        if args.empty?
+      # @api private
+      # Resolves everything to do with driver options:
+      #
+      # - Normalizes the label
+      # - Loads the driver class
+      # - Normalizes and extends options from the driver implementation
+      #
+      # @param label [Symbol, String] the driver label
+      # @param opts [Hash] driver options
+      def resolve_options(label, opts = nil)
+        if label.nil? or label.empty?
           raise ArgumentError, "Need at least one argument specifying the driver!"
         end
 
-        label = args[0].to_sym
+        label = label.to_sym
 
-        options = nil
-        if args.length > 1
-          if not args[1].nil? and not args[1].is_a? Hash
-            raise ArgumentError, "The second argument is expected to be an "\
-              "options hash!"
-          end
-          options = args[1]
+        if not opts.nil? and not opts.is_a? Hash
+          raise ArgumentError, "The second argument is expected to be an "\
+            "options Hash!"
         end
 
-        # Determine the driver class, if any
+        # Get the driver class.
         load_drivers
-
         driver_klass = get_driver(label)
         if not driver_klass
-          raise LoadError, "No driver implementation matching #{@label} found, "\
+          raise LoadError, "No driver implementation matching #{label} found, "\
             "aborting!"
         end
 
         # Sanitize options according to the driver's idea
-        if driver_klass.respond_to?(:sanitize_options)
-          label, options = driver_klass.sanitize_options(label, options)
+        options = opts
+        if driver_klass.respond_to?(:resolve_options)
+          label, options = driver_klass.resolve_options(label, opts)
         end
 
-        return label, options
+        return label, options, driver_klass
       end
 
       ##
+      # @api private
       # Load drivers; this loads all driver implementations included in this gem.
       # You can register external implementations with the :register_implementation
       # method.
@@ -124,7 +139,9 @@ module Unobtainium
       end
 
       ##
-      # Out of the loaded drivers, returns the one matching the label (if any)
+      # @api private
+      # Out of the loaded drivers, returns the one matching the label (if any).
+      # @param label [Symbol] The label matching a driver.
       def get_driver(label)
         # Of all the loaded classes, choose the first (unsorted) to match the
         # requested driver label
@@ -142,7 +159,16 @@ module Unobtainium
 
     ############################################################################
     # Public methods
-    attr_reader :label, :options, :impl
+
+    # @return [Symbol] the normalized label for the driver implementation
+    attr_reader :label
+
+    # @return [Hash] the options hash the driver implementation is using.
+    attr_reader :options
+
+    # @return [Object] the driver implementation itself; do not use this unless
+    #   you have to.
+    attr_reader :impl
 
     ##
     # Map any missing method to the driver implementation
@@ -153,6 +179,8 @@ module Unobtainium
       return super
     end
 
+    ##
+    # Map any missing method to the driver implementation
     def method_missing(meth, *args, &block)
       if not @impl.nil? and @impl.respond_to?(meth)
         return @impl.send(meth.to_s, *args, &block)
@@ -164,20 +192,11 @@ module Unobtainium
 
     ##
     # Initializer
-    def initialize(*args)
-      # Load drivers
-      ::Unobtainium::Driver.load_drivers
-
+    def initialize(label, opts = nil)
       # Sanitize options
-      @label, @options = ::Unobtainium::Driver.sanitize_options(*args)
-
-      # Get the driver class. We kind of know this works because
-      # sanitize_options does the same, but let's be strict.
-      driver_klass = ::Unobtainium::Driver.get_driver(label)
-      if not driver_klass
-        raise LoadError, "No driver implementation matching #{@label} found, "\
-          "aborting!"
-      end
+      @label, @options, driver_klass = ::Unobtainium::Driver.resolve_options(
+          label,
+          opts)
 
       # Perform precondition checks of the driver class
       driver_klass.ensure_preconditions(@label, @options)

data/lib/unobtainium/drivers/appium.rb

@@ -7,9 +7,11 @@
 # All rights reserved.
 #
 
-require_relative './support/util'
+require_relative '../support/util'
 
 module Unobtainium
+  # @api private
+  # Contains driver implementations
   module Drivers
 
     ##
@@ -27,14 +29,13 @@ module Unobtainium
       BROWSER_MATCHES = {
         android: {
           chrome: {
-            appPackage: 'com.android.chrome',
-            appActivity: 'com.google.android.apps.chrome.Main',
+            browserName: 'Chrome',
           },
         },
       }.freeze
 
       class << self
-        include ::Unobtainium::Drivers::Utility
+        include ::Unobtainium::Support::Utility
 
         ##
         # Return true if the given label matches this driver implementation,
@@ -55,7 +56,7 @@ module Unobtainium
 
         ##
         # Sanitize options, and expand the :browser key, if present.
-        def sanitize_options(label, options)
+        def resolve_options(label, options)
           # The label specifies the platform, if no other platform is given.
           normalized = normalize_label(label)
 
@@ -79,9 +80,7 @@ module Unobtainium
 
         ##
         # Create and return a driver instance
-        def create(label, options)
-          _, options = sanitize_options(label, options)
-
+        def create(_, options)
           # Create the driver
           driver = ::Appium::Driver.new(options).start_driver
           return driver
@@ -108,13 +107,17 @@ module Unobtainium
             return options
           end
 
-          # We have data, so we can remove the browser key itself
-          options.delete('browser')
-
           # We do have to check that we're not overwriting any of the keys.
-          data.keys.each do |key|
+          data.each do |key, value|
             key_s = key.to_s
-            if not options['caps'].key?(key) and not options['caps'].key?(key_s)
+            option_value = nil
+            if options['caps'].key?(key)
+              option_value = options['caps'][key]
+            elsif options['caps'].key?(key_s)
+              option_value = options['caps'][key_s]
+            end
+
+            if option_value.nil? or option_value == value
               next
             end
             raise ArgumentError, "You specified the browser option as, "\

data/lib/unobtainium/drivers/phantom.rb

@@ -0,0 +1,138 @@
+# coding: utf-8
+#
+# unobtainium
+# https://github.com/jfinkhaeuser/unobtainium
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other unobtainium contributors.
+# All rights reserved.
+#
+
+require_relative './selenium'
+require_relative '../support/util'
+require_relative '../support/port_scanner'
+require_relative '../support/runner'
+require_relative '../runtime'
+
+module Unobtainium
+  # @api private
+  # Contains driver implementations
+  module Drivers
+
+    ##
+    # Driver implementation using the selenium-webdriver gem to connect to
+    # PhantomJS.
+    class Phantom < Selenium
+      # Recognized labels for matching the driver
+      LABELS = {
+        phantomjs: [:headless,],
+      }.freeze
+
+      # Port scanning ranges (can also be arrays or single port numbers.
+      PORT_RANGES = [
+        9134,
+        8080,
+        8000..8079,
+        8081..10000,
+        1025..7999,
+        10001..65535,
+      ].freeze
+
+      # Timeout for waiting for connecting to PhantomJS server, in seconds
+      CONNECT_TIMEOUT = 60
+
+      class << self
+        include ::Unobtainium::Support::Utility
+        include ::Unobtainium::Support::PortScanner
+
+        ##
+        # Ensure that the driver's preconditions are fulfilled.
+        def ensure_preconditions(_, _)
+          super
+          begin
+            require 'phantomjs'
+          rescue LoadError => err
+            raise LoadError, "#{err.message}: you need to add "\
+                  "'phantomjs' to your Gemfile to use this driver!",
+                  err.backtrace
+          end
+        end
+
+        ##
+        # Mostly provides webdriver-specific options for PhantomJS
+        def resolve_options(label, options)
+          label, options = super
+
+          if not options[:phantomjs].nil? and not options['phantomjs'].nil?
+            raise ArgumentError, "Use either of 'phantomjs' or :phantomjs as "\
+                "option keys, not both!"
+          end
+          if not options[:phantomjs].nil?
+            options['phantomjs'] = options[:phantomjs]
+            options.delete(:phantomjs)
+          end
+
+          # Provide defaults for webdriver host and port. We find a free port
+          # here, so there's a possibility it'll get used before we run the
+          # server in #create. However, for the purpose of resolving options
+          # that's necessary. So we'll just live with this until it becomes a
+          # problem.
+          defaults = {
+            "phantomjs" => {
+              "host" => "localhost",
+              "port" => nil,
+            },
+          }
+          options = defaults.merge(options)
+
+          if options['phantomjs']['port'].nil?
+            ports = scan(options['phantomjs']['host'], *PORT_RANGES,
+                         for: :available, amount: :first)
+            if ports.empty?
+              raise "Could not find an available port for the PhantomJS server!"
+            end
+            options['phantomjs']['port'] = ports[0]
+          end
+
+          # Now override connection options for Selenium
+          options[:url] = "http://#{options['phantomjs']['host']}:"\
+              "#{options['phantomjs']['port']}"
+
+          return label, options
+        end
+
+        ##
+        # Create and return a driver instance
+        def create(_, options)
+          # Extract PhantomJS options
+          host = options['phantomjs']['host']
+          port = options['phantomjs']['port']
+          opts = options.dup
+          opts.delete('phantomjs')
+
+          # Start PhantomJS server, if it isn't already running
+          conn_str = "#{host}:#{port}"
+          runner = ::Unobtainium::Runtime.instance.store_with_if(conn_str) do
+            ::Unobtainium::Support::Runner.new(conn_str,
+                                               Phantomjs.path,
+                                               "--webdriver=#{conn_str}")
+          end
+          runner.start
+
+          # Wait for the server to open a port.
+          timeout = CONNECT_TIMEOUT
+          while timeout > 0 and not port_open?(host, port)
+            sleep 1
+            timeout -= 1
+          end
+          if timeout <= 0
+            raise "Timeout waiting to connect to PhantomJS!"
+          end
+
+          # Run Selenium against server
+          driver = ::Selenium::WebDriver.for(:remote, opts)
+          return driver
+        end
+      end # class << self
+    end # class PhantomJS
+  end # module Drivers
+end # module Unobtainium