Added 'helpers' object that exposes a collection of selenium helper methods

Author: John Doherty

Diff for: README.MD

@@ -98,6 +98,7 @@ The following variables are available within the ```Given()```, ```When()``` and
 | `selenium`  | the raw [selenium-webdriver](http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/) module, providing access to static properties/methods |
 | `page`      | collection of **page** objects loaded from disk and keyed by filename |
 | `shared`    | collection of **shared** objects loaded from disk and keyed by filename |
+| `helpers`   | a collection of helper methods _things selenium does not provide but really should!_ |
 | `by`        | the selenium [By](http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/index_exports_By.html) class used to locate elements on the page |
 | `until`     | the selenium [until](http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/lib/until.html) class used to wait for elements/events |
 | `expect`    | instance of [chai expect](http://chaijs.com/api/bdd/) to ```expect('something').to.equal('something')``` |

Diff for: runtime/helpers.js

@@ -0,0 +1,90 @@
+module.exports = {
+
+    /**
+     * returns a promise that is called when the url has loaded and the body element is present
+     * @param {string} url to load
+     * @returns {Promise}
+     * @example
+     *      helpers.loadPage('http://www.google.com');
+     */
+    loadPage: function(url, waitInSeconds) {
+
+        // use either passed in timeout or global 10 seconds default
+        var timeout = (waitInSeconds) ? (waitInSeconds * 1000) : DEFAULT_TIMEOUT;
+
+        // load the url and wait for it to complete
+        return driver.get(url).then(function() {
+
+            // now wait for the body element to be present
+            return driver.wait(until.elementLocated(by.css('body')), timeout);
+        });
+    },
+
+    /***
+     * returns the value of an attribute on an element   
+     * @param {string} css selector used to find the element
+     * @param {string} attribute name to retrieve
+     * @returns {string} the value of the attribute or empty string if not found
+     * @example
+     *      helpers.getAttributeValue('body', 'class');
+     */
+    getAttributeValue: function (selector, attributeName) {
+
+        // get the element from the page
+        return driver.findElement(by.css(selector)).then(function(attributeValue) {
+            return attributeValue;
+        })
+        .catch(function(){
+            return '';
+        });
+    },
+
+    /**
+     * returns list of elements matching a query selector who's inner text mathes param
+     * @param {string} css selector used to get list of elements
+     * @param {string} inner text to match (does not have to be visible)
+     * @returns {Promise}
+     * @example
+     *      helpers.getElementsContainingText('nav[role="navigation"] ul li a', 'Safety Boots')
+     */
+    getElementsContainingText: function(cssSelector, textToMatch) {
+
+        // method to execute within the DOM to find elements containing text
+        function findElementsContainingText(query, content) {
+
+            var results = []; // array to hold results
+
+            // workout which property to use to get inner text
+            var txtProp = ('textContent' in document) ? 'textContent' : 'innerText';
+
+            // get the list of elements to inspect
+            var elements = document.querySelectorAll(query);
+
+            for (var i=0, l=elements.length; i<l; i++) {
+                if (elements[i][txtProp] === content){
+                    results.push(elements[i]);
+                }
+            }
+
+            return results;
+        };
+
+        // grab matching elements
+        return driver.findElements(by.js(findElementsContainingText, cssSelector, textToMatch));
+    },
+
+    /**
+     * returns first elements matching a query selector who's inner text matches textToMatch param
+     * @param {string} css selector used to get list of elements
+     * @param {string} inner text to match (does not have to be visible)
+     * @returns {Promise}
+     * @example
+     *      helpers.getFirstElementContainingText('nav[role="navigation"] ul li a', 'Safety Boots').click();
+     */
+    getFirstElementContainingText: function(cssSelector, textToMatch){
+        return helpers.getElementsContainingText(cssSelector, textToMatch).then(function(elements){
+            return elements[0];
+        });
+    }
+
+};

Diff for: runtime/world.js

@@ -18,7 +18,7 @@ var fs = require('fs-plus'),
     assert = require("chai").assert,
     reporter = require('cucumber-html-reporter');
 
-var DEFAULT_TIMEOUT = 10 * 1000; // 10 second default
+global.DEFAULT_TIMEOUT = 10 * 1000; // 10 second default
 
 /**
  * create the selenium browser based on global var set in index.js
@@ -131,6 +131,8 @@ function World() {
         }
     };
 
+    // add helpers
+    global.helpers = require('../runtime/helpers.js');
 }
 
 // export the "World" required by cucubmer to allow it to expose methods within step def's