unobtainium 0.3.5 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 869c9481a4c19f67aad597d81ea044008012a2a3
-  data.tar.gz: 61af815e9e9ec60a432966efd2b0c7348848341f
+  metadata.gz: 97948bc83a14acdbe6c71e330e66e907d2a19fe7
+  data.tar.gz: 33ad8b54a05cd91a90935896378bdba28d9f12cb
 SHA512:
-  metadata.gz: 1e1309efacab5bd98dcb243eba59f3c8327537d5006449d73ed68e3d78e2112936386ac4f2bb635fa9e9d636389cfc4123ac79a7a2feebb3c0b52247d654d100
-  data.tar.gz: e7a91f3b0a399159d691bed04a0648967cdd16835041c2aec8e4dfa454c5a66e3f3cfb8bee7db273a1cc49bab2b06274f99ba7b6a08ecd87b228adf2b7484ae5
+  metadata.gz: 63da85ce1551f33687e11cbb1d59577303907797e8c0cf1a935d692d9922cfb8cf8ace0f30bdd4badc5f97245cc5449127f734952865e3121bc0c58f60266987
+  data.tar.gz: a737bd06d28b979976cd56ac4bd82ab7f918b21d32b6a84a036bb0b1706e9a6103580fa0acef97ce60533d161d5eb45fd77515df3c8e99e84438278b639954e8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unobtainium (0.3.5)
+    unobtainium (0.4.0)
       sys-proctable (~> 1.0)
 
 GEM
@@ -79,7 +79,7 @@ GEM
     simplecov-html (0.10.0)
     sys-proctable (1.0.0)
     tomlrb (1.2.1)
-    unicode-display_width (1.0.3)
+    unicode-display_width (1.0.5)
     websocket (1.2.3)
     yard (0.8.7.6)
 
@@ -88,7 +88,7 @@ PLATFORMS
 
 DEPENDENCIES
   appium_lib
-  bundler (~> 1.11)
+  bundler (~> 1.12)
   codeclimate-test-reporter
   cucumber
   phantomjs
@@ -101,4 +101,4 @@ DEPENDENCIES
   yard (~> 0.8)
 
 BUNDLED WITH
-   1.11.2
+   1.12.1

data/README.md

@@ -79,9 +79,20 @@ The configuration file knows two configuration variables:
 See the documentation on [configuration features](docs/CONFIGURATION.md) for
 details.
 
-## Development
+# Development
 
 - [driver development](docs/DRIVERS.md)
+- [driver module development](docs/DRIVER_MODULES.md)
+
+# Additional Drivers
+
+- [unobtainium-nokogiri](https://github.com/jfinkhaeuser/unobtainium-nokogiri) is
+  a nokogiri-based driver for entirely browserless access to XML and HTML files
+  and pages.
+- [unobtainium-faraday](https://github.com/jfinkhaeuser/unobtainium-faraday) is
+  a faraday-based driver for dealing with RESTish APIs.
+- [unobtainium-kramdown](https://github.com/jfinkhaeuser/unobtainium-kramdown) is
+  a faraday-based driver for dealing with Markdown structured text.
 
 # Credits
 This gem is inspired by [LapisLazuli](https://github.com/spriteCloud/lapis-lazuli),

data/docs/DRIVER_MODULES.md

@@ -0,0 +1,66 @@
+# Driver Modules
+
+Driver modules are a way for extending drivers from other gems. It really is
+little more than a glorified version of Ruby's `extend` mechanism, but fairly
+convenient.
+
+Suppose you're using any of the built-in drivers with the Selenium API. That
+API is fairly verbose when it comes to e.g. handling waiting for an element to
+appear. You have to create a `Wait` object and use it to loop over `#find_element`
+until a timeout occurs or the latter returns an element.
+
+Much simpler to just have a `#wait` method, no?
+
+```ruby
+module WaitModule
+  def wait
+    # some clever implementation
+  end # wait
+end # module WaitModule
+```
+
+You can just extend the driver that unobtainium returns, of course:
+
+```ruby
+drv = driver(:firefox)
+drv.extend(WaitModule)
+```
+
+However, you will have to do this for every driver you instanciate. So let's
+simplify this a bit.
+
+## Module Registration
+
+Instead of having to extend every driver yourself, unobtainium allows you to
+register your `WaitModule` with the `Driver` class, and unobtainium takes care
+of the extension for you:
+
+```ruby
+::Unobtainium::Driver.register_module(WaitModule, __FILE__)
+drv = driver(:firefox)
+drv.respond_to?(:wait) # => true
+```
+
+## Module Matching
+
+The only problem with the above is that our hypothetical `#wait` function relies
+heavily on the driver behaving like Selenium, having e.g. a `#find_element`
+function. So unobtainium also allows your module implementation to decide whether
+it wants to extend a particular driver instance or not.
+
+```ruby
+module WaitModule
+  class << self
+    def matches?(impl)
+      # Only extend drivers with (at least) a `#find_element` method.
+      impl.respond_to?(:find_element)
+    end
+  end # class << self
+
+  def wait
+    # some clever implementation
+  end # wait
+end # module WaitModule
+```
+
+In fact, `#matches?` is a mandatory method for module implementations.

data/lib/unobtainium/driver.rb

@@ -70,6 +70,41 @@ module Unobtainium
         @@drivers[klass] = fpath
       end
 
+      ##
+      # Add a new driver module. 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.
+      #
+      # Driver modules must implement the class methods listed in `MODULE_METHODS`.
+      #
+      # @param klass (Class) Driver implementation class to register.
+      # @param path (String) Implementation path of the driver class.
+      def register_module(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 MODULE_METHODS - klass_methods != []
+          raise LoadError, "Driver module #{klass.name} is not implementing all "\
+            "of the class methods #{MODULE_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 @@modules.include?(klass) and @@modules[klass] != fpath
+          raise LoadError, "Driver module #{klass.name} is duplicated in file "\
+            "'#{fpath}'; previous definition is here: "\
+            "'#{@@modules[klass]}'"
+        end
+
+        # If all of that was ok, we can register the implementation.
+        @@modules[klass] = fpath
+      end
+
       private :new
 
       ##
@@ -174,8 +209,8 @@ module Unobtainium
 
     ##
     # Map any missing method to the driver implementation
-    def respond_to?(meth)
-      if not @impl.nil? and @impl.respond_to?(meth)
+    def respond_to_missing?(meth, include_private = false)
+      if not @impl.nil? and @impl.respond_to?(meth, include_private)
         return true
       end
       return super
@@ -205,12 +240,20 @@ module Unobtainium
 
       # Great, instanciate!
       @impl = driver_klass.create(@label, @options)
+
+      # Now also extend this implementation with all the modues that match
+      @@modules.each do |klass, _|
+        if klass.matches?(@impl)
+          @impl.extend(klass)
+        end
+      end
     end
 
     # Class variables have their place, rubocop... still, err on the strict
     # side and just skip this check here.
     # rubocop:disable Style/ClassVars
     @@drivers = {}
+    @@modules = {}
     # rubocop:enable Style/ClassVars
 
     # Methods that drivers must implement
@@ -219,5 +262,10 @@ module Unobtainium
       :ensure_preconditions,
       :create
     ].freeze
+
+    # Methods that driver modules must implement
+    MODULE_METHODS = [
+      :matches?
+    ].freeze
   end # class Driver
 end # module Unobtainium

data/lib/unobtainium/pathed_hash.rb

@@ -154,8 +154,8 @@ module Unobtainium
 
     ##
     # Map any missing method to the Hash implementation
-    def respond_to?(meth)
-      if not @data.nil? and @data.respond_to?(meth)
+    def respond_to_missing?(meth, include_private = false)
+      if not @data.nil? and @data.respond_to?(meth, include_private)
         return true
       end
       return super

data/lib/unobtainium/version.rb

@@ -8,5 +8,5 @@
 #
 module Unobtainium
   # The current release version
-  VERSION = "0.3.5".freeze
+  VERSION = "0.4.0".freeze
 end

data/spec/driver_spec.rb

@@ -5,6 +5,33 @@ require_relative './mock_driver.rb'
 class FakeDriver
 end # class FakeDriver
 
+module TestModule
+  class << self
+    def matches?(_)
+      # Always match!
+      true
+    end
+  end # class << self
+
+  def my_module_func
+  end
+end # module TestModule
+
+module NonMatchingTestModule
+  class << self
+    def matches?(_)
+      # Never match!
+      false
+    end
+  end # class << self
+
+  def does_not_exist
+  end
+end # module NonMatchingTestModule
+
+module FakeModule
+end # module FakeModule
+
 describe ::Unobtainium::Driver do
   before :each do
     ::Unobtainium::Driver.register_implementation(MockDriver, "mock_driver.rb")
@@ -18,7 +45,8 @@ describe ::Unobtainium::Driver do
 
   it "refuses to register the same driver twice from different locations" do
     expect do
-      ::Unobtainium::Driver.register_implementation(MockDriver, __FILE__)
+      ::Unobtainium::Driver.register_implementation(MockDriver, __FILE__ + '1')
+      ::Unobtainium::Driver.register_implementation(MockDriver, __FILE__ + '2')
     end.to raise_error(LoadError)
   end
 
@@ -62,4 +90,46 @@ describe ::Unobtainium::Driver do
     drv = ::Unobtainium::Driver.create(:mock, foo: 42)
     expect(drv.passed_options).to eql foo: 42
   end
+
+  describe 'modules' do
+    it 'will register a module' do
+      expect do
+        ::Unobtainium::Driver.register_module(TestModule, __FILE__)
+      end.not_to raise_error(LoadError)
+    end
+
+    it 'refuses to register the same module twice' do
+      expect do
+        ::Unobtainium::Driver.register_module(TestModule, __FILE__ + '1')
+        ::Unobtainium::Driver.register_module(TestModule, __FILE__ + '2')
+      end.to raise_error(LoadError)
+    end
+
+    it 'refuses to register a module with the wrong interface' do
+      expect do
+        ::Unobtainium::Driver.register_module(FakeModule, __FILE__)
+      end.to raise_error(LoadError)
+    end
+
+    it 'extends a driver with a registered module' do
+      expect do
+        ::Unobtainium::Driver.register_module(TestModule, __FILE__)
+      end.not_to raise_error(LoadError)
+
+      drv = ::Unobtainium::Driver.create(:mock)
+
+      expect(drv.respond_to?(:my_module_func)).to be_truthy
+    end
+
+    it 'does not extend a driver with a non-matching module' do
+      expect do
+        ::Unobtainium::Driver.register_module(TestModule, __FILE__)
+        ::Unobtainium::Driver.register_module(NonMatchingTestModule, __FILE__)
+      end.not_to raise_error(LoadError)
+
+      drv = ::Unobtainium::Driver.create(:mock)
+
+      expect(drv.respond_to?(:does_not_exist)).to be_falsy
+    end
+  end
 end

data/unobtainium.gemspec

@@ -42,7 +42,7 @@ Gem::Specification.new do |spec|
   spec.requirements  = "Either or all of 'selenium-webdriver', 'appium_lib', "\
                        "'phantomjs'"
 
-  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "bundler", "~> 1.12"
   spec.add_development_dependency "rubocop", "~> 0.39"
   spec.add_development_dependency "rake", "~> 11.1"
   spec.add_development_dependency "rspec", "~> 3.4"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unobtainium
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.4.0
 platform: ruby
 authors:
 - Jens Finkhaeuser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-27 00:00:00.000000000 Z
+date: 2016-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '1.12'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -186,6 +186,7 @@ files:
 - config/config.yml
 - docs/CONFIGURATION.md
 - docs/DRIVERS.md
+- docs/DRIVER_MODULES.md
 - features/step_definitions/steps.rb
 - features/support/env.rb
 - features/world.feature