unobtainium 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9921b8f7735c0d00216208fe5ad193525671fd8f
-  data.tar.gz: 1557e2461fc29570eb97f975d83a4b792b838862
+  metadata.gz: 3aa9b74f8f1f3c7d408438a0cff087c268dc89d4
+  data.tar.gz: 31f3f35f5ff7b1eccf2fd121c233b62d0056c386
 SHA512:
-  metadata.gz: bd7643c1a36ea61aa917629a922cd3535b408f70a4206e18d77cebcd11327e0cb13931589eef0b7367c9c243928fd9c23ea82196397fce2bc756db9edbed1f85
-  data.tar.gz: f435d50ed4e50e697dbe1b7b1a3c0ddf5ccc50c2148d4d02cb5fea2ac30e7d738e59c47371655a4ccb449bb56c24a66760abebd7838fc22dd0cdecd973c00af6
+  metadata.gz: 953d864dd1286c499979044503a8655426f9e14912878d8ebd9300a3ddc9492143c8efe2f014168a44fe7131286107ba318c3c0509591832fda7fd67611dd667
+  data.tar.gz: a5bfa05e01c37fd7a8f6a6e15d05227f9552971d708d65fa4a54a290d742d50f0152f95ad55cf9dc51bd6bcf5ee7c44cfc2574caf85cf32069cda8f20ed2fe04

data/.rubocop.yml

@@ -64,3 +64,6 @@ Style/TrailingUnderscoreVariable:
 
 Style/NumericLiterals:
   Enabled: false
+
+Style/FileName:
+  Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unobtainium (0.2.1)
+    unobtainium (0.3.1)
       sys-proctable (~> 1.0)
 
 GEM
@@ -37,11 +37,11 @@ GEM
     gherkin (3.2.0)
     json (1.8.3)
     mini_portile2 (2.0.0)
-    multi_json (1.11.2)
+    multi_json (1.11.3)
     multi_test (0.1.2)
     nokogiri (1.6.7.2)
       mini_portile2 (~> 2.0.0.rc2)
-    parser (2.3.0.7)
+    parser (2.3.1.0)
       ast (~> 2.2)
     phantomjs (2.1.1.0)
     powerpack (0.1.1)
@@ -66,7 +66,7 @@ GEM
       rainbow (>= 1.99.1, < 3.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (~> 1.0, >= 1.0.1)
-    ruby-progressbar (1.7.5)
+    ruby-progressbar (1.8.0)
     rubyzip (1.2.0)
     selenium-webdriver (2.53.0)
       childprocess (~> 0.5)

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) Jens Finkhaeuser (http://finkhaeuser.de/) and other unobtainum
+Copyright (c) Jens Finkhaeuser (http://finkhaeuser.de/) and other unobtainium
 contributors. All rights not covered below are reserved.
 
 The MIT +no-false-attribs License (MITNFA)

data/README.md

@@ -24,6 +24,8 @@ also added.
 You can use unobtainium on its own, or use it as part of a
 [cucumber](https://cucumber.io/) test suite.
 
+[![Unobtainium Demonstration](http://img.youtube.com/vi/82pYWG5uTnM/0.jpg)](http://www.youtube.com/watch?v=82pYWG5uTnM)
+
 Unobtainium's functionality is in standalone classes, but it's all combined in
 the `Unobtainium::World` module.
 
@@ -36,7 +38,7 @@ the `Unobtainium::World` module.
 
 - The `Config` class is a `PathedHash`, but also reads JSON or YAML files to
   initialize itself with values. See the documentation on [configuration features](docs/CONFIGURATION.md)
-  for details
+  for details.
 - The `Runtime` class is a singleton and a `Hash`-like container (but simpler),
   that destroys all of its contents at the end of a script, calling custom
   destructors if required. That allows for clean teardown and avoids everything
@@ -74,6 +76,13 @@ The configuration file knows two configuration variables:
   options hash you might otherwise pass to `Driver.create` as the second
   parameter.
 
+See the documentation on [configuration features](docs/CONFIGURATION.md) for
+details.
+
+## Development
+
+- [driver development](docs/DRIVERS.md)
+
 # Credits
 This gem is inspired by [LapisLazuli](https://github.com/spriteCloud/lapis-lazuli),
 but vastly less complex, and aims to stay so.

data/docs/CONFIGURATION.md

@@ -170,7 +170,9 @@ drivers:
 The tests can be run on device/browser farms. Typically you only need to
 configure drivers, much like for mobile testing. The following example
 is for [TestingBot](https://testingbot.com). Note that each farm expects
-different configuration keys for selecting browsers and for authentication.
+different configuration keys for selecting browsers and for authentication,
+and that `unobtainium` just passes these values through to Selenium and/or
+Appium.
 
 ```yaml
 # config/config.yml

data/docs/DRIVERS.md

@@ -0,0 +1,102 @@
+# Drivers
+
+Drivers are used to access web pages and their content. Since unobtainium is
+designed to be primarily a wrapper for Selenium and Appium, the built-in
+drivers provide roughly the same API, but there is no strict requirement for
+this.
+
+Driver implementations are classes which are required to have a number of
+class methods, described below. No requirements on instance methods are made.
+
+# Required Class Methods
+
+The class methods required by unobtainium are as follows:
+
+- `matches?` accepting a String or Symbol label, as passed by the user to
+  `Driver#create`. Must return true if the driver implementation matches this
+  label, i.e. if this driver implementation is to be used when the user
+  specifies this particular label.
+  Note that multiple driver implementations can match the same label; the order
+  of preference is an implementation detail.
+- *[optional]* `resolve_options` accepting the label and options passed to
+  `Driver#create` by the user (defaulting to an empty hash). The function must
+  return the label and options again, however should normalize the label (see
+  below) and supplement any options with default values, etc.
+- `ensure_preconditions` accepting the label, and options.
+  The method should be used to require any necessary code, and raise errors if
+  any other preconditions are not met. See the section on dynamic loading as
+  well.
+- Finally, `create` accepting the label and options should return an instance
+  of a driver class matching both parameters.
+
+# Optional Instance Methods
+
+- `destroy` gets invoked by `Runtime` at exit, if `World#driver` is used to
+  create the instance. It can be used to tear down the driver instance cleanly.
+
+# Label Normalization & Configuration Resolution
+
+The built-in drivers respond to many different labels, some of which are
+aliases for a *normalized* label. For example, you can specify `:headless`,
+which is an alias for `:phantomjs`.
+
+Label normalization should return `:phantomjs` in the example above.
+
+The main goal behind configuration resolution is to provide a way for driver
+implementations to translate configuration keys into a form better suited to
+the implementation.
+
+For example, the Selenium driver symbolizes keys, because `selenium-webdriver`
+requires symbol keys. On the other hand, the [configuration](./CONFIGURATION.md)
+system produces String keys only.
+
+But you can use this step also to expand shortcut options. The Appium implentation
+allows you to more simply specify some mobile browsers, expanding this into
+capabilities required by Appium itself.
+
+# Instance Management
+
+The `World#driver` function registers driver implementations with `Runtime` to
+be destroyed at exit.
+
+In order to allow multiple driver instances for e.g. multi-browser testing, but
+simultaneously manage instances as described above, the normalized label and
+resolved configuration (see above) are used to generate unique keys.
+
+The basic principle is that `World#driver` will be called multiple times in a
+test suite. If it is invoked twice with the same parameters, the same instance
+should be returned. Parameterless invocations should always return the same
+instance, as defined by the configuration. For the pattern inclined reader, this
+is an implementation of the [flyweight pattern](https://en.wikipedia.org/wiki/Flyweight_pattern).
+
+Therefore, `resolve_options` should return identical results for two invocations
+with *semantically* identical input.
+
+# Dynamic Loading
+
+In order not to create hard dependencies in unobtainium on specific versions of
+Selenium, Appium and PhantomJS, these dependencies are only required when
+`ensure_preconditions` is being invoked. That lets users decide which versions
+to require, and skip libraries they do not use.
+
+Your driver implementation does not have to follow the same pattern, unless you
+want to see it merged into unobtainium itself.
+
+# Registering an Implementation
+
+When you have written your class to conform to the above API, all that is left
+to do is to register it with unobtainium:
+
+```ruby
+class MyDriver
+  # implementatin
+end # class MyDriver
+
+::Unobtainium::Driver.register_implementation(MyDriver, __FILE__)
+```
+
+The second path parameter should always be set to `__FILE__`. It is used to
+ensure that if your library is included multiple times, the driver does not
+get registered more than once. On the other hand, a different implementation
+with the same class name would raise an error when `register_implementation`
+is invoked.

data/lib/unobtainium/pathed_hash.rb

@@ -27,6 +27,17 @@ module Unobtainium
   class PathedHash
     include RecursiveMerge
 
+    DEFAULT_PROC = proc do |hash, key|
+      case key
+      when String
+        sym = key.to_sym
+        hash[sym] if hash.key?(sym)
+      when Symbol
+        str = key.to_s
+        hash[str] if hash.key?(str)
+      end
+    end.freeze
+
     ##
     # Initializer. Accepts `nil`, hashes or pathed hashes.
     #
@@ -38,6 +49,8 @@ module Unobtainium
         @data = init.dup
       end
       @separator = '.'
+
+      @data.default_proc = DEFAULT_PROC
     end
 
     # @return [String] the separator is the character or pattern splitting paths.
@@ -106,6 +119,7 @@ module Unobtainium
         # For write methods, we need to create intermediary hashes.
         leaf = recursive_fetch(components, @data,
                                create: WRITE_METHODS.include?(method))
+        leaf.default_proc = DEFAULT_PROC
 
         # If we have a leaf, we want to send the requested method to that
         # leaf.

data/lib/unobtainium/version.rb

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

data/lib/unobtainium/world.rb

@@ -36,7 +36,11 @@ module Unobtainium
     # Return the global configuration, loaded from `World#config_file`
     def config
       return ::Unobtainium::Runtime.instance.store_with_if(:config) do
-        ::Unobtainium::Config.load_config(::Unobtainium::World.config_file)
+        begin
+          ::Unobtainium::Config.load_config(::Unobtainium::World.config_file)
+        rescue Errno::ENOENT
+          {}
+        end
       end
     end
 

data/spec/pathed_hash_spec.rb

@@ -54,6 +54,31 @@ describe ::Unobtainium::PathedHash do
     expect(ph["bar.nope"]).to eql nil
   end
 
+  it "can be used with indifferent access from string key" do
+    sample = {
+      "foo" => 42,
+    }
+    ph = ::Unobtainium::PathedHash.new(sample)
+
+    expect(ph["foo"]).to eql 42
+    expect(ph[:foo]).to eql 42
+  end
+
+  it "can be used with indifferent access from symbol key" do
+    sample = {
+      foo: 42,
+      bar: {
+        baz: 'quux',
+      }
+    }
+    ph = ::Unobtainium::PathedHash.new(sample)
+
+    expect(ph["foo"]).to eql 42
+    expect(ph[:foo]).to eql 42
+
+    expect(ph['bar.baz']).to eql 'quux'
+  end
+
   it "treats a single separator as the root" do
     sample = { "foo" => 42 }
     ph = ::Unobtainium::PathedHash.new(sample)

data/spec/spec_helper.rb

@@ -1,7 +1,11 @@
+# Only start CodeClimate from travis
+if ENV['CODECLIMATE_REPO_TOKEN']
+  require 'codeclimate-test-reporter'
+  CodeClimate::TestReporter.start
+end
+
+# Always start SimpleCov
 require 'simplecov'
 SimpleCov.start do
   add_filter 'unobtainium/drivers'
 end
-
-require "codeclimate-test-reporter"
-CodeClimate::TestReporter.start

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unobtainium
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Jens Finkhaeuser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-04-19 00:00:00.000000000 Z
+date: 2016-04-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -185,6 +185,7 @@ files:
 - Rakefile
 - config/config.yml
 - docs/CONFIGURATION.md
+- docs/DRIVERS.md
 - features/step_definitions/steps.rb
 - features/support/env.rb
 - features/world.feature