added html attribute helpers and updated docs

John Doherty · John Doherty · commit 8ba693fcd07d · 2017-11-26T13:35:56.000Z
diff --git a/README.MD b/README.MD
@@ -1,4 +1,4 @@
-# selenium-cucumber-js [![Shippable branch](https://img.shields.io/shippable/5818b23bbd56670e00037040/master.svg)](https://app.shippable.com/projects/5818b23bbd56670e00037040) [![npm](https://img.shields.io/npm/dt/selenium-cucumber-js.svg)](https://www.npmjs.com/package/selenium-cucumber-js) 
+# selenium-cucumber-js [![Shippable branch](https://img.shields.io/shippable/5818b23bbd56670e00037040/master.svg)](https://app.shippable.com/projects/5818b23bbd56670e00037040) [![npm](https://img.shields.io/npm/dt/selenium-cucumber-js.svg)](https://www.npmjs.com/package/selenium-cucumber-js) [![Twitter Follow](https://img.shields.io/twitter/follow/CambridgeMVP.svg?style=social&label=Twitter&style=plastic)](https://twitter.com/CambridgeMVP)
 
 JavaScript browser automation framework using official [selenium-webdriver](http://seleniumhq.github.io/selenium/docs/api/javascript/ "view webdriver js documentation") and [cucumber-js](https://github.com/cucumber/cucumber-js "view cucumber js documentation").
 
@@ -12,6 +12,7 @@ JavaScript browser automation framework using official [selenium-webdriver](http
   * [Step definitions](#step-definitions)
   * [Page objects](#page-objects)
   * [Shared objects](#shared-objects)
+  * [Helpers](#helpers)
   * [Visual Comparison](#visual-comparison)
   * [Before/After hooks](#beforeafter-hooks)
   * [Reports](#reports)
@@ -233,6 +234,36 @@ module.exports = function () {
 };
 ```
 
+### Helpers
+
+`selenium-cucumber-js` contains a few helper methods to make working with selenium a bit easier, those methods are:
+
+```js
+// Load a URL, returning only when the <body> tag is present
+helpers.loadPage('http://www.google.com');
+
+// get the value of a HTML attribute
+helpers.getAttributeValue('body', 'class');
+
+// get a list of elements matching a query selector who's inner text matches param.
+helpers.getElementsContainingText('nav[role="navigation"] ul li a', 'Safety Boots')
+
+// get first elements matching a query selector who's inner text matches textToMatch param
+helpers.getFirstElementContainingText('nav[role="navigation"] ul li a', 'Safety Boots').click();
+
+// click element(s) that are not visible (useful in situations where a menu needs a hover before a child link appears)
+helpers.clickHiddenElement('nav[role="navigation"] ul li a','Safety Boots');
+
+// wait until a HTML attribute equals a particular value
+helpers.waitUntilAttributeEquals('html', 'data-busy', 'false', 5000);
+
+// wait until a HTML attribute exists
+helpers.waitUntilAttributeExists('html', 'data-busy', 5000);
+
+// wait until a HTML attribute no longer exists
+helpers.waitUntilAttributeDoesNotExists('html', 'data-busy', 5000);
+```
+
 ### Visual Comparison
 
 The `selenium-cucumber-js` framework uses [Applitools Eyes](https://applitools.com/) to add visual checkpoints to your JavaScript Selenium tests. It takes care of getting screenshots of your application from the underlying WebDriver, sending them to the Applitools Eyes server for validation and failing the test when differences are detected. To preform visual comparisons within your tests, obtain an [Applitools Eyes](https://applitools.com/) API Key and assign it to the `eye_key` property of the `selenium-cucumber-js.json` config file in the root of your project.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "selenium-cucumber-js",
-  "version": "1.5.5",
+  "version": "1.5.6",
   "description": "JavaScript browser automation framework using official selenium-webdriver and cucumber-js",
   "main": "index.js",
   "scripts": {
diff --git a/runtime/helpers.js b/runtime/helpers.js
@@ -134,24 +134,87 @@ module.exports = {
      * @param {integer} waitInMilliseconds - number of milliseconds to wait for page to load
      * @returns {Promise} resolves if attribute eventually equals, otherwise rejects
      * @example
-     *      helpers.waitUntilAttributeEquals('html', 'data-busy', 'false', 5);
+     *      helpers.waitUntilAttributeEquals('html', 'data-busy', 'false', 5000);
      */
     waitUntilAttributeEquals: function(elementSelector, attributeName, attributeValue, waitInMilliseconds) {
 
         // use either passed in timeout or global default
         var timeout = waitInMilliseconds || DEFAULT_TIMEOUT;
 
+        // readable error message
+        var timeoutMessage = attributeName + ' does not equal ' + attributeValue + ' after ' + waitInMilliseconds + ' milliseconds';
+
         // repeatedly execute the test until it's true or we timeout
         return driver.wait(function() {
 
-            // get the html attribute value using another helper method
+            // get the html attribute value using helper method
             return helpers.getAttributeValue(elementSelector, attributeName).then(function(value) {
 
                 // inspect the value
                 return value === attributeValue;
             });
 
-        }, timeout);
+        }, timeout, timeoutMessage);
+    },
+
+    /**
+     * Waits until a HTML attribute exists
+     * @param {string} elementSelector - HTML element CSS selector
+     * @param {string} attributeName - name of the attribute to inspect
+     * @param {integer} waitInMilliseconds - number of milliseconds to wait for page to load
+     * @returns {Promise} resolves if attribute exists within timeout, otherwise rejects
+     * @example
+     *      helpers.waitUntilAttributeExists('html', 'data-busy', 5000);
+     */
+    waitUntilAttributeExists: function(elementSelector, attributeName, waitInMilliseconds) {
+
+        // use either passed in timeout or global default
+        var timeout = waitInMilliseconds || DEFAULT_TIMEOUT;
+
+        // readable error message
+        var timeoutMessage = attributeName + ' does not exists after ' + waitInMilliseconds + ' milliseconds';
+
+        // repeatedly execute the test until it's true or we timeout
+        return driver.wait(function() {
+
+            // get the html attribute value using helper method
+            return helpers.getAttributeValue(elementSelector, attributeName).then(function(value) {
+
+                // attribute exists if value is not null
+                return value !== null;
+            });
+
+        }, timeout, timeoutMessage);
+    },
+
+    /**
+     * Waits until a HTML attribute no longer exists
+     * @param {string} elementSelector - HTML element CSS selector
+     * @param {string} attributeName - name of the attribute to inspect
+     * @param {integer} waitInMilliseconds - number of milliseconds to wait for page to load
+     * @returns {Promise} resolves if attribute is removed within timeout, otherwise rejects
+     * @example
+     *      helpers.waitUntilAttributeDoesNotExists('html', 'data-busy', 5000);
+     */
+    waitUntilAttributeDoesNotExists: function(elementSelector, attributeName, waitInMilliseconds) {
+
+        // use either passed in timeout or global default
+        var timeout = waitInMilliseconds || DEFAULT_TIMEOUT;
+
+        // readable error message
+        var timeoutMessage = attributeName + ' still exists after ' + waitInMilliseconds + ' milliseconds';
+
+        // repeatedly execute the test until it's true or we timeout
+        return driver.wait(function() {
+
+            // get the html attribute value using helper method
+            return helpers.getAttributeValue(elementSelector, attributeName).then(function(value) {
+
+                // attribute exists if value is not null
+                return value === null;
+            });
+
+        }, timeout, timeoutMessage);
     }
 
 };

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "selenium-cucumber-js",`
`3`		`- "version": "1.5.5",`
	`3`	`+ "version": "1.5.6",`
`4`	`4`	`"description": "JavaScript browser automation framework using official selenium-webdriver and cucumber-js",`
`5`	`5`	`"main": "index.js",`
`6`	`6`	`"scripts": {`