unobtainium 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 234ce137a967d3cbf7343bc5dce74f6a3a606339
-  data.tar.gz: 4bd93c4402adf6a379f1037b70958941018e805f
+  metadata.gz: 9921b8f7735c0d00216208fe5ad193525671fd8f
+  data.tar.gz: 1557e2461fc29570eb97f975d83a4b792b838862
 SHA512:
-  metadata.gz: 7899a9aefc8410150b42f930d8a770fff850883284026551b25edd9e30bdf152117b5510e88e192b2e21b097346e5cc8e773ee2bdbe945bf5a72a4641032e683
-  data.tar.gz: f718847acf4c4600caa0f5a7b37dd76c0e5cf468b3d1993582aae3bdfbb2092d4fcc94ece7942c6e906029dbc0cf825a6dc491438981b68c140634be9a3c4846
+  metadata.gz: bd7643c1a36ea61aa917629a922cd3535b408f70a4206e18d77cebcd11327e0cb13931589eef0b7367c9c243928fd9c23ea82196397fce2bc756db9edbed1f85
+  data.tar.gz: f435d50ed4e50e697dbe1b7b1a3c0ddf5ccc50c2148d4d02cb5fea2ac30e7d738e59c47371655a4ccb449bb56c24a66760abebd7838fc22dd0cdecd973c00af6

data/.gitignore

@@ -37,3 +37,7 @@ build/
 
 # Editor files
 .*.sw*
+
+# Cucumber
+C:\\nppdf32Log\\debuglog.txt
+config/*-local.yml

data/.rubocop.yml

@@ -58,3 +58,9 @@ Style/TrailingCommaInLiteral:
 
 Style/FirstParameterIndentation:
   Enabled: false
+
+Style/TrailingUnderscoreVariable:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false

data/Gemfile.lock

@@ -2,18 +2,48 @@ PATH
   remote: .
   specs:
     unobtainium (0.2.1)
+      sys-proctable (~> 1.0)
 
 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)
+    builder (3.2.2)
+    childprocess (0.5.9)
+      ffi (~> 1.0, >= 1.0.11)
     codeclimate-test-reporter (0.5.0)
       simplecov (>= 0.7.1, < 1.0.0)
+    cucumber (2.3.3)
+      builder (>= 2.1.2)
+      cucumber-core (~> 1.4.0)
+      cucumber-wire (~> 0.0.1)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 3.2.0)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.1.2)
+    cucumber-core (1.4.0)
+      gherkin (~> 3.2.0)
+    cucumber-wire (0.0.1)
     diff-lcs (1.2.5)
     docile (1.1.5)
+    ffi (1.9.10)
+    gherkin (3.2.0)
     json (1.8.3)
+    mini_portile2 (2.0.0)
+    multi_json (1.11.2)
+    multi_test (0.1.2)
+    nokogiri (1.6.7.2)
+      mini_portile2 (~> 2.0.0.rc2)
     parser (2.3.0.7)
       ast (~> 2.2)
+    phantomjs (2.1.1.0)
     powerpack (0.1.1)
     rainbow (2.1.0)
     rake (11.1.2)
@@ -37,24 +67,38 @@ 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)
     simplecov (0.11.2)
       docile (~> 1.1.0)
       json (~> 1.8)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.0)
+    sys-proctable (1.0.0)
+    tomlrb (1.2.1)
     unicode-display_width (1.0.3)
+    websocket (1.2.3)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  appium_lib
   bundler (~> 1.11)
   codeclimate-test-reporter
+  cucumber
+  phantomjs
   rake (~> 11.1)
   rspec (~> 3.4)
   rubocop (~> 0.39)
+  selenium-webdriver
   simplecov (~> 0.11)
   unobtainium!
+  yard (~> 0.8)
 
 BUNDLED WITH
    1.11.2

data/README.md

@@ -9,6 +9,8 @@ so that test code can more easily cover:
   - Mobile browsers
   - Mobile apps
 
+The gem also wraps [PhantomJS](http://phantomjs.org/) for headless testing.
+
 Some additional useful functionality for the maintenance of test suites is
 also added.
 
@@ -26,26 +28,27 @@ Unobtainium's functionality is in standalone classes, but it's all combined in
 the `Unobtainium::World` module.
 
 - The `PathedHash` class extends `Hash` by allowing paths to nested values, e.g.:
-  ```ruby
-  h = PathedHash.new { "foo" => { "bar" => 42 }}
-  h["foo.bar"] == 42 # true
-  ```
-- The `Config` class is a `PathedHash`, but also reads JSON or YAML files to
-  initialize itself with values, and allows config paths to be overridden by
-  environment variables: `FOO_BAR` overrides the "foo.bar" path.
 
-  You can use JSON as environment variable values.
+    ```ruby
+    h = PathedHash.new { "foo" => { "bar" => 42 }}
+    h["foo.bar"] == 42 # true
+    ```
+
+- 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
 - 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
-  to have to implement the Singleton pattern itself.
+  having to implement the Singleton pattern itself.
 - The `Driver` class, of course, wraps either of Appium or Selenium drivers:
-  ```ruby
-  drv = Driver.create(:firefox) # uses Selenium
-  drv = Driver.create(:android) # uses Appium
 
-  drv.navigate.to "..." # delegates to Selenium or Appium
-  ```
+    ```ruby
+    drv = Driver.create(:firefox) # uses Selenium
+    drv = Driver.create(:android) # uses Appium
+
+    drv.navigate.to "..." # delegates to Selenium or Appium
+    ```
 
 ## World
 

data/Rakefile

@@ -1,16 +1,32 @@
 # Rubocop
 require 'rubocop/rake_task'
-RuboCop::RakeTask.new
+RuboCop::RakeTask.new(:rubocop)
 
 # Rspec
 require 'rspec/core/rake_task'
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:rspec)
+
+# Cucumber
+require 'cucumber'
+require 'cucumber/rake/task'
+Cucumber::Rake::Task.new(:cuke) do |t|
+  t.cucumber_opts = "--fail-fast --format=pretty --expand "\
+                    "--order=random --backtrace"
+end
+
+# Documentation
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+  t.options = ['-m', 'markdown']
+  t.stats_options = ['--list-undoc']
+end
 
 # Combined test task
-desc "Test the code"
+desc "Test all the things!"
 task :test do
   Rake::Task[:rubocop].invoke
-  Rake::Task[:spec].invoke
+  Rake::Task[:rspec].invoke
 end
 
 # Default is the test task

data/config/config.yml

@@ -0,0 +1,14 @@
+---
+drivers:
+  firefox:
+  android:
+    browser: chrome
+  android_remote:
+    extends: remote
+    desired_capabilities:
+      platform: "ANDROID"
+      browserName: "galaxy_nexus"
+  remote:
+    url: "http://hub.testingbot.com:4444/wd/hub"
+driver: firefox
+at_end: quit

data/docs/CONFIGURATION.md

@@ -0,0 +1,250 @@
+# Configuration
+
+The `Config` class, and it's major user, the `World.config` method make using
+complex configuration files in your project easier.
+
+## Basic Configuration Features
+
+### Pathed Access
+
+`Config` is a `Hash` with pathed access. Take a nested structure such as this
+as an example:
+
+```yaml
+---
+foo:
+  bar: baz
+```
+
+Instead of accessing `config['foo']['bar']`, you can instead use a path such
+as `config['foo.bar']`. The major benefit is that if *any* of the path components
+does not exist, nil is returned (and the behaviour is equivalent to other access
+methods such as `:fetch`, etc.)
+
+Similarly you can use this type of access for writing: `config['baz.quux'] = 42`
+will create both the `baz` hash, and it's child the `quux` key.
+
+### Configuration Loading
+
+If you're using `World.config`, configuration is automatically loaded at the
+time it's first invoked from the location specified by `World.config_file`, which
+defaults to `config/config.yml`.
+
+This is equivalent to invoking `Config.load_config` with that location manually.
+
+### Local Configuration Overrides
+
+For the example file of `config/config.yml`, if a file with the same path and
+name, and the name postfix `-local` exists (i.e. `config/config-local.yml`), that
+file will also be loaded. It's keys will be recursively added to the keys from the
+main configuration file, overwriting only leaves, not entire hashes.
+
+Example:
+
+```yaml
+# config/config.yml
+---
+foo:
+  bar: 42
+  baz: quux
+
+# config/config-local.yml
+---
+something: else
+foo:
+  baz: override
+
+# result
+---
+something: else
+foo:
+  bar: 42
+  baz: override
+```
+
+### Configuration Extension
+
+An additional feature of the `Config` class is that you can extend individual
+hashes with values from other hashes.
+
+```yaml
+---
+root:
+  foo: bar
+derived:
+  baz: quux
+  extends: root
+```
+
+This results in:
+
+```yaml
+---
+root:
+  foo: bar
+derived:
+  baz: quux
+  foo: bar
+  base: root
+```
+
+**Notes:**
+
+- This feature means that `extends` and `base` are reserved configuration keys!
+- Multiple levels of extension are supported. The `base` keyword will *always
+  name the root-most element*, not the immediate ancestor.
+- Extending from multiple bases is not supported.
+- Extending from nonexistent bases is supported; all that happens is that the
+  `base` key is set.
+
+### Environment Variable Override
+
+Given a configuration path, any environment variable with the same name (change
+path to upper case letters and replace `.` with `_`, e.g. `foo.bar` becomes
+`FOO_BAR`) overrides the values in the configuration file.
+
+If the environment variable is parseable as JSON, then that parsed JSON will
+**replace** the original configuration path (i.e. it will not be merged).
+
+## Configuration Values Interpreted by World
+
+- The `driver` path specifies which driver to use; the value shold be a label
+  recognized by the `Driver.create` method.
+- The `drivers` (plural) path contains options for the different drivers. Each
+  driver configuration is nested under a key matching a `Driver.create` label,
+  e.g.
+  ```yaml
+  ---
+  drivers:
+    firefox:
+      some: option
+  ```
+- The `at_end` path specifies what should be done with the driver when the
+  script ends. Possible values are `close` and `quit`, and the default is `quit`.
+
+## Driver Configurations
+
+You can create quite complex driver configurations with the above features, for
+very convenient test suite development.
+
+### Select Driver
+
+Typically, you will configure all drivers in use by your test suite in the
+`drivers` section of the configuration file. Then, use the `DRIVER` environment
+variable to override/set which driver to use:
+
+```bash
+$ DRIVER=chrome bundle exec my_tests
+```
+
+### Mobile
+
+When running mobile test suites, [Appium](https://github.com/appium/appium)
+requires that you identify the app and/or device you want to run tests against.
+
+That typically means specifying parts of a configuration that is applicable to
+any user of the test code, and specifying parts that are applicable only to an
+individual.
+
+Use the local configuration override to achieve this split:
+
+```yaml
+# config/config.yml
+---
+drivers:
+  android:
+    caps:
+      platformName: android
+      ...
+
+# config/config-local.yml
+---
+drivers:
+  android:
+    caps:
+      deviceName: deadbeef
+```
+
+### Browser/Device Farms
+
+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.
+
+```yaml
+# config/config.yml
+drivers:
+  remote:
+    url: "http://hub.testingbot.com:4444/wd/hub"
+    desired_capabilities:
+      platform: "WIN8"
+      browserName: "chrome"
+      version: "35"
+```
+
+It's good practice to keep authentication data out of the github repository,
+so the TestingBot API key and secret should live only in `config/config-local.yml`.
+
+```yaml
+# config/config-local.yml
+drivers:
+  remote:
+    desired_capabilities:
+      api_key: "1ceb00da"
+      api_secret: "cefaedfe"
+```
+
+Then run:
+
+```bash
+$ DRIVER=remote bundle exec cucumber
+```
+
+### Complex Configurations
+
+With device/browser farms in particular, you typically do not want to use a
+single `remote` configuration, but rather one for each remote browser or
+device you want to use in testing. This is possible with the configuration
+extension mechanism:
+
+```yaml
+# config/config.yml
+---
+drivers:
+  remote:
+    url: "http://hub.testingbot.com:4444/wd/hub"
+  remote_win8_chrome:
+    extends: remote
+    desired_capabilities:
+      platform: "WIN8"
+      browserName: "chrome"
+      version: "35"
+
+# config/config-local.yml
+---
+drivers:
+  remote:
+    desired_capabilities:
+      api_key: "1ceb00da"
+      api_secret: "cefaedfe"
+```
+
+As noted in the section on the extension mechanism, the `extends` keyword
+gets replaced with a `base` keyword that contains the *root-most* element.
+In this case, `drivers.remote_win8_chrome.base` becomes `remote`, but even if
+you had a `drivers.remote_win8_chrome38` section that overrides the desired
+chrome version, `drivers.remote_win8_chrome38.base` would still become
+`remote`.
+
+The `World.config` method makes use of this, and replaces the driver label
+you specified with the `driver` path or `DRIVER` environment variable with
+this `base` value. The effect is that you can give your driver configuration
+sections any name, as long as they're eventually extended by a section with
+a key that `Driver.create` recognizes.
+
+Thus, the following starts Chrome 35 on Windows 8 on TestingBot:
+
+```bash
+$ DRIVER=remote_win8_chrome bundle exec my_test
+```