unobtainium 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a7dfaed7fd3b12c6c2506ec09194c34f9939ef16
-  data.tar.gz: 535afb416ce0449d2d4a96bfc5a57cbcd8a93224
+  metadata.gz: 194953d1b77be115316598397b69e99037647085
+  data.tar.gz: 9194ccf829bcf5c6e98027251716b8598ea1979b
 SHA512:
-  metadata.gz: dec4e9b74f39c887ce315209cd340363eca9b02bc47e9637337b7195b1dabe467ee3a69e66f41fde71400afcfddfa1a453a83a1a9a757fb818f5a81ade292091
-  data.tar.gz: 8599bcf5b567faf0294cd6c1fbb820b06d64a61c413f4979427a3527ed39b97867d9cb4f891b63b55e7a2ea8cfa4aaa030b9803862a0961051b21a613bbe776e
+  metadata.gz: 2e43f762d2c90323173cdfeedc2d57e764114558282066bd28a9208ed1fb175deb71917b23cbc135e8f476770e5c396414a572dcb2814ecd5e93449999cb1a8a
+  data.tar.gz: 58fd4916229bf0528304c9cb18541f5b6f2431e958da9f7154b70f1a553ffc04e26be791a02442c0e858ce45e1d42e98bb8c8f9f48e6f9a7fa6866843432baac

data/Gemfile

@@ -2,6 +2,3 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in unobtainium.gemspec
 gemspec
-
-gem 'selenium-webdriver'
-gem 'appium_lib'

data/Gemfile.lock

@@ -6,21 +6,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    appium_lib (8.0.2)
-      awesome_print (~> 1.6)
-      json (~> 1.8)
-      nokogiri (~> 1.6.6)
-      selenium-webdriver (~> 2.49)
-      tomlrb (~> 1.1)
     ast (2.2.0)
-    awesome_print (1.6.1)
-    childprocess (0.5.9)
-      ffi (~> 1.0, >= 1.0.11)
-    ffi (1.9.10)
-    json (1.8.3)
-    mini_portile2 (2.0.0)
-    nokogiri (1.6.7.2)
-      mini_portile2 (~> 2.0.0.rc2)
     parser (2.3.0.7)
       ast (~> 2.2)
     powerpack (0.1.1)
@@ -32,23 +18,14 @@ GEM
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
     ruby-progressbar (1.7.5)
-    rubyzip (1.2.0)
-    selenium-webdriver (2.53.0)
-      childprocess (~> 0.5)
-      rubyzip (~> 1.0)
-      websocket (~> 1.0)
-    tomlrb (1.2.0)
     unicode-display_width (1.0.3)
-    websocket (1.2.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  appium_lib
   bundler (~> 1.11)
   rubocop (~> 0.39)
-  selenium-webdriver
   unobtainium!
 
 BUNDLED WITH

data/README.md

@@ -12,6 +12,8 @@ so that test code can more easily cover:
 Some additional useful functionality for the maintenance of test suites is
 also added.
 
+[![Gem Version](https://badge.fury.io/rb/unobtainium.svg)](https://badge.fury.io/rb/unobtainium)
+
 # Credits
 This gem is inspired by [LapisLazuli](https://github.com/spriteCloud/lapis-lazuli),
 but vastly less complex, and aims to stay so.

data/lib/unobtainium/config.rb

@@ -0,0 +1,170 @@
+# coding: utf-8
+#
+# unobtainium
+# https://github.com/jfinkhaeuser/unobtainium
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other unobtainium contributors.
+# All rights reserved.
+#
+
+require 'pathname'
+
+require 'unobtainium/pathed_hash'
+
+module Unobtainium
+  ##
+  # The Config class extends PathedHash by two main pieces of functionality:
+  # a) it loads configuration files and turns them into pathed hashes, and
+  # b) 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
+  # 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'.
+  #
+  # 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.
+  #
+  class Config < PathedHash
+    # Very simple YAML parser
+    class YAMLParser
+      require 'yaml'
+
+      def self.parse(string)
+        YAML.load(string)
+      end
+    end
+
+    # Very simple JSON parser
+    class JSONParser
+      require 'json'
+
+      def self.parse(string)
+        JSON.parse(string)
+      end
+    end
+
+    PathedHash::READ_METHODS.each do |method|
+      # Wrap all read functions into something that checks for environment
+      # variables first.
+      define_method(method) do |*args, &block|
+        # We'll make it rather simple: since the first argument is a key, we
+        # will just transform it to the matching environment variable name,
+        # and see if that environment variable is set.
+        env_name = args[0].upcase.gsub(split_pattern, '_')
+        contents = ENV[env_name]
+
+        # No environment variable set? Fine, just do the usual thing.
+        if contents.nil?
+          return super(*args, &block)
+        end
+
+        # With an environment variable, we will try to parse it as JSON first.
+        begin
+          return JSONParser.parse(contents)
+        rescue JSON::ParserError
+          return contents
+        end
+      end
+    end
+
+    class << self
+      # Mapping of file name extensions to parser types.
+      FILE_TO_PARSER = {
+        '.yml'  => YAMLParser,
+        '.yaml' => YAMLParser,
+        '.json' => JSONParser,
+      }.freeze
+
+      # If the config file contains an Array, this is what they key of the
+      # returned Hash will be.
+      ARRAY_KEY = 'config'.freeze
+
+      ##
+      # Loads a configuration file with the given file name. The format is
+      # detected based on one of the extensions in FILE_TO_PARSER.
+      def load_config(path)
+        # Load base and local configuration files
+        base, config = load_base_config(path)
+        _, local_config = load_local_config(base)
+
+        # We can't sensibly merge arrays and hashes, so bail if the two classes
+        # don't match.
+        if config.class != local_config.class
+          raise ArgumentError, "Config file and local override file do not have "\
+                "the same top-level structure (hash or array), and therefore "\
+                "cannot be merged!"
+        end
+
+        # Merge
+        if config.is_a? Array
+          config = { ARRAY_KEY => config.push(*local_config) }
+        elsif config.is_a? Hash
+          # rubocop:disable Style/CaseEquality
+          merger = proc do |_, v1, v2|
+            Hash === v1 && Hash === v2 ? v1.merge(v2, &merger) : v2
+          end
+          # rubocop:enable Style/CaseEquality
+          config.merge!(local_config, &merger)
+        else
+          raise "Unexpected top-level structure in configuration file: "\
+                "#{config.class}"
+        end
+
+        return Config.new(config)
+      end
+
+      private
+
+      def load_base_config(path)
+        # Make sure the format is recognized early on.
+        base = Pathname.new(path)
+        formats = FILE_TO_PARSER.keys
+        if not formats.include?(base.extname)
+          raise ArgumentError, "Files with extension '#{base.extname}' are not"\
+                " recognized; please use one of #{formats}!"
+        end
+
+        # Don't check the path whether it exists - loading a nonexistent
+        # file will throw a nice error for the user to catch.
+        file = base.open
+        contents = file.read
+
+        # Parse the contents.
+        config = FILE_TO_PARSER[base.extname].parse(contents)
+
+        return base, config
+      end
+
+      def load_local_config(base)
+        # Now construct a file name for a local override.
+        local = Pathname.new(base.dirname)
+        local = local.join(base.basename(base.extname).to_s + "-local" +
+            base.extname)
+        puts local
+        if not local.exist?
+          return Config.new(config)
+        end
+
+        # We know the local override file exists, but we do want to let any errors
+        # go through that come with reading or parsing it.
+        file = local.open
+        contents = file.read
+
+        local_config = FILE_TO_PARSER[base.extname].parse(contents)
+
+        return local, local_config
+      end
+    end # class << self
+  end # class Config
+end # module Unobtainium

data/lib/unobtainium/driver.rb

@@ -23,23 +23,77 @@ module Unobtainium
       ##
       # Create a driver instance with the given arguments
       def create(*args)
-        Driver.new(*args)
+        new(*args)
       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
+      # parameter.
+      #
+      # Using file names lets us figure out whether the class is a duplicate,
+      # or merely a second registration of the same class.
+      def register_implementation(klass, path)
+        # We need to deal with absolute paths only
+        fpath = File.absolute_path(path)
+
+        # Figure out if the class implements all the methods we need; we're not
+        # checking for anything else.
+        klass_methods = klass.methods - klass.instance_methods - Object.methods
+
+        if DRIVER_METHODS - klass_methods != []
+          raise LoadError, "Driver #{klass.name} is not implementing all of "\
+            "the class methods #{DRIVER_METHODS}, aborting!"
+        end
+
+        # The second question is whether the same class is already known, or
+        # whether a class with the same name but under a different location is
+        # known.
+        if @@drivers.include?(klass) and @@drivers[klass] != fpath
+          raise LoadError, "Driver #{klass.name} is duplicated in file "\
+            "'#{fpath}'; previous definition is here: "\
+            "'#{@@drivers[klass]}'"
+        end
+
+        # If all of that was ok, we can register the implementation.
+        @@drivers[klass] = fpath
+      end
+
+      private :new
     end # class << self
 
     ############################################################################
     # Public methods
     attr_reader :label, :options, :impl
 
+    ##
+    # Map any missing method to the driver implementation
+    def respond_to?(meth)
+      if not @impl.nil? and @impl.respond_to?(meth)
+        return true
+      end
+      return super
+    end
+
+    def method_missing(meth, *args, &block)
+      if not @impl.nil? and @impl.respond_to?(meth)
+        return @impl.send(meth.to_s, *args, &block)
+      end
+      return super
+    end
+
+    private
+
     ##
     # Initializer
     def initialize(*args)
-      # Sanitize options
-      @label, @options = sanitize_options(*args)
-
       # Load drivers
       load_drivers
 
+      # Sanitize options
+      @label, @options = sanitize_options(*args)
+
       # Determine the driver class, if any
       driver_klass = get_driver(@label)
       if not driver_klass
@@ -54,8 +108,6 @@ module Unobtainium
       @impl = driver_klass.create(@label, @options)
     end
 
-    private
-
     # Class variables have their place, rubocop... still, err on the strict
     # side and just skip this check here.
     # rubocop:disable Style/ClassVars
@@ -70,18 +122,31 @@ module Unobtainium
     ].freeze
 
     ##
-    # FIXME
+    # Ensures arguments are according to expectations.
     def sanitize_options(*args)
-      load_drivers
-      require 'pp'
-      pp args
+      if args.empty?
+        raise ArgumentError, "Need at least one argument specifying the driver!"
+      end
+
+      label = args[0].to_sym
+
+      options = nil
+      if args.length > 1
+        if not args[1].is_a? Hash
+          raise ArgumentError, "The second argument is expected to be an options "\
+            "hash!"
+        end
+        options = args[1]
+      end
+
+      return label, options
     end
 
     ##
-    # Load drivers.
+    # Load drivers; this loads all driver implementations included in this gem.
+    # You can register external implementations with the :register_implementation
+    # method.
     def load_drivers
-      # TODO: add load path for external drivers, or let them be specified via
-      #       the driver environment/config variables.
       pattern = File.join(File.dirname(__FILE__), 'drivers', '*.rb')
       Dir.glob(pattern).each do |fpath|
         # Determine class name from file name
@@ -92,20 +157,7 @@ module Unobtainium
           require fpath
           klassname = 'Unobtainium::Drivers::' + fname
           klass = Object.const_get(klassname)
-          klass_methods = klass.methods - klass.instance_methods - Object.methods
-
-          if DRIVER_METHODS - klass_methods != []
-            raise LoadError, "Driver #{klassname} is not implementing all of "\
-              "#{DRIVER_METHODS}, aborting!"
-          end
-
-          if @@drivers.include?(klass) and @@drivers[klass] != fpath
-            raise LoadError, "Driver #{klassname} is duplicated in file "\
-              "'#{fpath}'; previous definition is here: "\
-              "'#{@@drivers[klass]}'"
-          end
-          @@drivers[klass] = fpath
-
+          Driver.register_implementation(klass, fpath)
         rescue LoadError => err
           raise LoadError, "#{err.message}: unknown problem loading driver, "\
             "aborting!"

data/lib/unobtainium/pathed_hash.rb

@@ -0,0 +1,121 @@
+# coding: utf-8
+#
+# unobtainium
+# https://github.com/jfinkhaeuser/unobtainium
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other unobtainium contributors.
+# All rights reserved.
+#
+
+module Unobtainium
+
+  ##
+  # The PathedHash class wraps Hash by offering pathed access on top of
+  # regular access, i.e. instead of h["first"]["second"] you can write
+  # h["first.second"]
+  class PathedHash
+    ##
+    # Initializer
+    def initialize(init = {})
+      @data = init
+      @separator = '.'
+    end
+
+    # The separator is the character or pattern splitting paths
+    attr_accessor :separator
+
+    READ_METHODS = [
+      :[], :default, :delete, :fetch, :has_key?, :include?, :key?, :member?,
+    ].freeze
+    WRITE_METHODS = [
+      :[]=, :store,
+    ].freeze
+
+    ##
+    # Returns the pattern to split paths at
+    def split_pattern
+      /(?<!\\)#{Regexp.escape(@separator)}/
+    end
+
+    (READ_METHODS + WRITE_METHODS).each do |method|
+      # Wrap all accessor functions to deal with paths
+      define_method(method) do |*args, &block|
+        # With any of the dispatch methods, we know that the first argument has
+        # to be a key. We'll try to split it by the path separator.
+        components = args[0].to_s.split(split_pattern)
+
+        # This PathedHash is already the leaf-most Hash
+        if components.length == 1
+          return @data.send(method, *args, &block)
+        end
+
+        # Deal with other paths. The frustrating part here is that for nested
+        # hashes, only this outermost one is guaranteed to know anything about
+        # path splitting, so we'll have to recurse down to the leaf here.
+        #
+        # For write methods, we need to create intermediary hashes.
+        leaf = recursive_fetch(components, @data,
+                               create: WRITE_METHODS.include?(method))
+
+        # If the leaf is nil, we can't send it any method without raising
+        # an error. We'll instead send the method to an empty hash, to mimic
+        # the correct behaviour.
+        if leaf.nil?
+          return {}.send(method, *args, &block)
+        end
+
+        # If we have a leaf, we want to send the requested method to that
+        # leaf.
+        copy = args.dup
+        copy[0] = components.last
+        return leaf.send(method, *copy, &block)
+      end
+    end
+
+    def to_s
+      @data.to_s
+    end
+
+    ##
+    # Map any missing method to the driver implementation
+    def respond_to?(meth)
+      if not @data.nil? and @data.respond_to?(meth)
+        return true
+      end
+      return super
+    end
+
+    def method_missing(meth, *args, &block)
+      if not @data.nil? and @data.respond_to?(meth)
+        return @data.send(meth.to_s, *args, &block)
+      end
+      return super
+    end
+
+    private
+
+    ##
+    # Given the path components, recursively fetch any but the last key.
+    def recursive_fetch(path, data, options = {})
+      # For the leaf element, we do nothing because that's where we want to
+      # dispatch to.
+      if path.length == 1
+        return data
+      end
+
+      # Split path into head and tail; for the next iteration, we'll look use only
+      # head, and pass tail on recursively.
+      head = path[0]
+      tail = path.slice(1, path.length)
+
+      # If we're a write function, then we need to create intermediary objects,
+      # i.e. what's at head if nothing is there.
+      if options[:create] and data.fetch(head, nil).nil?
+        data[head] = {}
+      end
+
+      # Ok, recurse.
+      return recursive_fetch(tail, data[head], options)
+    end
+  end # class PathedHash
+end # module Unobtainium

data/lib/unobtainium/runtime.rb

@@ -0,0 +1,126 @@
+# coding: utf-8
+#
+# unobtainium
+# https://github.com/jfinkhaeuser/unobtainium
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other unobtainium contributors.
+# All rights reserved.
+#
+require 'singleton'
+
+module Unobtainium
+
+  ##
+  # The Runtime class is a singleton scoped to destroy itself when script
+  # execution stops. It's also an object map, which will destroy all object
+  # it contains when it destroys itself.
+  #
+  # Therefore, it can be used as a way to register object instances for
+  # destruction at script end.
+  class Runtime
+    include Singleton
+
+    ##
+    # Initializer
+    def initialize
+      @objects = {}
+
+      # Create our own finalizer
+      ObjectSpace.define_finalizer(self) do
+        @objects.keys.each do |key|
+          unset(key)
+        end
+      end
+    end
+
+    ##
+    # Number of objects stored in the object map
+    def length
+      return @objects.length
+    end
+
+    ##
+    # Does an object with the given name exist?
+    def has?(name)
+      return @objects.key?(name)
+    end
+
+    ##
+    # Store the given object under the given name. This overwrites any objects
+    # already stored under that name, which are destroyed before the new object
+    # is stored.
+    #
+    # If a destructor is passed, it is used to destroy the *new* object only.
+    # If no destructor is passed and the object responds to a :destroy method, that
+    # method is called.
+    def set(name, object, destructor = nil)
+      unset(name)
+
+      @objects[name] = [object, destructor]
+
+      return object
+    end
+
+    ##
+    # Store the object returned by the block, if any. If no object is returned
+    # or no block is given, this function does nothing.
+    #
+    # Otherwise it works much like :set above.
+    def set_with(name, destructor = nil, &block)
+      object = nil
+      if not block.nil?
+        object = yield
+      end
+
+      if object.nil?
+        return
+      end
+
+      return set(name, object, destructor)
+    end
+
+    ##
+    # Unsets (and destroys) any object found under the given name.
+    def unset(name)
+      if not @objects.key?(name)
+        return
+      end
+
+      obj, dtor = @objects[name]
+      @objects.delete(name)
+      destroy(obj, dtor)
+    end
+
+    ##
+    # Returns the object with the given name, or the default value if no such
+    # object exists.
+    def fetch(name, default = nil)
+      return @objects.fetch(name, default)
+    end
+
+    ##
+    # Similar to :fetch, but always returns nil for an object that could not
+    # be found.
+    def [](name)
+      return @objects[name]
+    end
+
+    private
+
+    ##
+    # Destroy the given object with the destructor provided.
+    def destroy(object, destructor)
+      if not destructor.nil?
+        destructor.call
+        return
+      end
+
+      if not object.respond_to?(:destroy)
+        return
+      end
+
+      object.send(:destroy)
+    end
+  end # class Runtime
+
+end # module Unobtainium

data/lib/unobtainium/version.rb

@@ -7,5 +7,5 @@
 # All rights reserved.
 #
 module Unobtainium
-  VERSION = "0.0.1".freeze
+  VERSION = "0.0.2".freeze
 end

data/unobtainium.gemspec

@@ -20,11 +20,8 @@ Gem::Specification.new do |spec|
   spec.email         = ["jens@finkhaeuser.de"]
   spec.description   = %q(
     Unobtainium wraps Selenium and Appium in a simple driver abstraction so that
-    test code can more easily cover:
-
-      - Desktop browsers
-      - Mobile browsers
-      - Mobile apps
+    test code can more easily cover desktop browsers, mobile browsers and mobile
+    apps.
 
     Some additional useful functionality for the maintenance of test suites is
     also added.
@@ -40,6 +37,10 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.required_ruby_version = '>= 1.9'
+
+  spec.requirements  = "Either or all of 'selenium-webdriver', 'appium_lib'"
+
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rubocop", "~> 0.39"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unobtainium
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Jens Finkhaeuser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-07 00:00:00.000000000 Z
+date: 2016-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -39,9 +39,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.39'
 description: "\n    Unobtainium wraps Selenium and Appium in a simple driver abstraction
-  so that\n    test code can more easily cover:\n\n      - Desktop browsers\n      -
-  Mobile browsers\n      - Mobile apps\n\n    Some additional useful functionality
-  for the maintenance of test suites is\n    also added.\n  "
+  so that\n    test code can more easily cover desktop browsers, mobile browsers and
+  mobile\n    apps.\n\n    Some additional useful functionality for the maintenance
+  of test suites is\n    also added.\n  "
 email:
 - jens@finkhaeuser.de
 executables: []
@@ -55,9 +55,12 @@ files:
 - LICENSE
 - README.md
 - lib/unobtainium.rb
+- lib/unobtainium/config.rb
 - lib/unobtainium/driver.rb
 - lib/unobtainium/drivers/appium.rb
 - lib/unobtainium/drivers/selenium.rb
+- lib/unobtainium/pathed_hash.rb
+- lib/unobtainium/runtime.rb
 - lib/unobtainium/version.rb
 - unobtainium.gemspec
 homepage: https://github.com/jfinkhaeuser/unobtainium
@@ -72,13 +75,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '1.9'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-requirements: []
+requirements:
+- Either or all of 'selenium-webdriver', 'appium_lib'
 rubyforge_project: 
 rubygems_version: 2.4.5.1
 signing_key: