feat: Add various value getting and checking instructions

setViewport, selectOptionByIndex, selectOptionByValue, hasAttribute,
hasClass, hasValue, hasText, hasInnerHtml, hasOuterHtml, isEnabled,
isExisting, isFocused, isSelected, isVisible, isVisibleWithinViewport,
isNotEnabled, isNotExisting, isNotFocused, isNotSelected, isNotVisible,
isNotVisibleWithinViewport

Author: prantlf

Gruntfile.js

@@ -247,6 +247,90 @@ module.exports = function (grunt) {
                   }
                 });
             }
+          },
+          {
+            url: 'http://localhost:8881/test/pages/values.html',
+            isEnabled: 'select',
+            isExisting: 'select',
+            isFocused: 'select',
+            isVisible: 'select',
+            isVisibleWithinViewport: 'select',
+            isNotEnabled: 'input',
+            isNotExisting: 'textarea',
+            isNotFocused: 'input',
+            isNotVisible: 'input',
+            isNotVisibleWithinViewport: 'input',
+            hasAtribute: {
+              selector: 'input',
+              name: 'disabled',
+              value: 'disabled'
+            },
+            hasValue: {
+              selector: 'input',
+              value: 'test'
+            },
+            hasText: {
+              selector: 'div',
+              value: 'Text'
+            },
+            hasInnerHtml: {
+              selector: 'div',
+              value: 'Text'
+            },
+            hasOuterHtml: {
+              selector: 'div',
+              value: '<div class="class" tabindex="0">Text</div>'
+            }
+          },
+          {
+            hasClass: {
+              selector: 'div',
+              value: 'class'
+            }
+          },
+          {
+            hasClass: {
+              selector: 'div',
+              value: '!none'
+            }
+          },
+          {
+            hasClass: {
+              selector: 'div',
+              value: 'class none'
+            }
+          },
+          {
+            selectOptionByIndex: {
+              selector: 'select',
+              index: 1
+            },
+            hasValue: {
+              selector: 'select',
+              value: '2'
+            }
+          },
+          {
+            selectOptionByValue: {
+              selector: 'select',
+              value: '1'
+            },
+            hasValue: {
+              selector: 'select',
+              value: '1'
+            }
+          },
+          {
+            setViewport: {
+              width: 768,
+              height: 480
+            }
+          },
+          {
+            setViewport: {}
+          },
+          {
+            setViewport: {}
           }
         ],
         scenarios: 'test/scenarios/*.js'

README.md

@@ -219,15 +219,36 @@ You can use sub-tasks, `commands` and `scenarios` to structure your code and exe
 
 One of the instructions has to be present in every command. These properties are evaluated (and their effect is executed) in the order, in which they are listed below:
 
+* setViewport
 * url
 * go
 * clearValue
 * setValue
 * addValue
+* selectOptionByIndex
+* selectOptionByValue
 * moveCursor
 * click
 * keys
 * wait
+* hasAttribute
+* hasClass
+* hasValue
+* hasText
+* hasInnerHtml
+* hasOuterHtml
+* isEnabled
+* isExisting
+* isFocused
+* isSelected
+* isVisible
+* isVisibleWithinViewport
+* isNotEnabled
+* isNotExisting
+* isNotFocused
+* isNotSelected
+* isNotVisible
+* isNotVisibleWithinViewport
 * file
 
 #### url
@@ -313,6 +334,44 @@ Appends to the current value of an input element. The object should contain the
 }
 ```
 
+#### selectOptionByIndex
+Type: `Object`
+
+Select an `option` element of a `select` element by the specified (zero-based)
+index. The object should contain the following properties:
+
+* `selector` - `String` - selector of a select element.
+* `index` - `Number` - numeric (0-based integer) index of an option to select.
+
+```js
+{
+  url: 'https://example.com',
+  setValue: {
+    selector: 'select',
+    index: 1 // select second option
+  }
+}
+```
+
+#### selectOptionByValue
+Type: `Object`
+
+Select an `option` element of a `select` element by the specified value of
+the `value` attribute. The object should contain the following properties:
+
+* `selector` - `String` - selector of a select element.
+* `value` - `String` - value of the `value` attribute of an option to select.
+
+```js
+{
+  url: 'https://example.com',
+  setValue: {
+    selector: 'select',
+    value: 'second'
+  }
+}
+```
+
 #### moveCursor
 Type: `String` | `Object`
 
@@ -664,6 +723,7 @@ your code using Grunt.
 
 ## Release History
 
+ * 2018-02-26  [v0.5.0]  Allow checking and setting various properties
  * 2018-02-22  [v0.4.0]  Allow sending key strokes to the browser
  * 2018-01-30  [v0.3.0]  Allow specifying test commands in separate modules
  * 2018-01-27  [v0.2.0]  Allow saving screenshots in addition to snapshots

tasks/html-dom-snapshot.js

@@ -13,8 +13,14 @@ const fs = require('fs'),
       path = require('path'),
       mkdirp = require('mkdirp'),
       instructions = [
-        'url', 'go', 'clearValue', 'setValue', 'addValue', 'moveCursor',
-        'click', 'keys', 'wait'
+        'setViewport', 'url', 'go', 'clearValue', 'setValue', 'addValue',
+        'selectOptionByIndex', 'selectOptionByValue', 'moveCursor',
+        'click', 'keys', 'wait', 'hasAttribute', 'hasClass', 'hasValue',
+        'hasText', 'hasInnerHtml', 'hasOuterHtml',
+        'isEnabled', 'isExisting', 'isFocused', 'isSelected', 'isVisible',
+        'isVisibleWithinViewport', 'isNotEnabled', 'isNotExisting',
+        'isNotFocused', 'isNotSelected', 'isNotVisible',
+        'isNotVisibleWithinViewport'
       ].map(function (instruction) {
         return require('./instructions/' + instruction);
       });
@@ -44,11 +50,15 @@ module.exports = function (grunt) {
           target = this.target,
           pages = data.pages,
           snapshots = options.dest,
+          viewport = options.viewport,
+          lastViewport = {
+            width: viewport.width,
+            height: viewport.height
+          },
           client = webdriverio.remote({
             desiredCapabilities: options.browserCapabilities
           });
-    var lastViewport = options.viewport,
-        urlCount = 0,
+    var urlCount = 0,
         snapshotCount = 0,
         screenshotCount = 0,
         commands;
@@ -145,7 +155,9 @@ module.exports = function (grunt) {
     }
 
     function performCommand(command) {
-      const commandOptions = Object.assign({}, options, command.options || {}),
+      const commandOptions = Object.assign({
+              lastViewport: lastViewport
+            }, options, command.options || {}),
             file = command.file,
             viewport = commandOptions.viewport,
             screenshots = commandOptions.screenshots,
@@ -170,9 +182,10 @@ module.exports = function (grunt) {
                         'in the target "' + target + '".\n' +
                         JSON.stringify(command));
       }
-      if (viewport.width !== lastViewport.width ||
-          viewport.height !== lastViewport.height) {
-        lastViewport = viewport;
+      if ((viewport.width !== lastViewport.width ||
+          viewport.height !== lastViewport.height) && !lastViewport.explicit) {
+        lastViewport.width = viewport.width;
+        lastViewport.height = viewport.height;
         viewportSet = setViewportSize();
       } else {
         viewportSet = Promise.resolve();
@@ -182,8 +195,10 @@ module.exports = function (grunt) {
       }
       return commandInstructions.reduce(function (previous, instruction) {
           return previous.then(function () {
-            if (instruction.detected) {
-              return instruction.perform(grunt, target, client, command, commandOptions);
+            const detected = instruction.detected;
+            if (detected) {
+              return instruction.perform(grunt, target, client, command,
+                                         commandOptions, detected);
             }
           });
         }, viewportSet)

tasks/instructions/go.js

@@ -7,7 +7,8 @@ module.exports = {
 
   perform: function (grunt, target, client, command) {
     const go = command.go;
-    if (!(go === 'back' || go === 'forward' || go === 'refresh')) {
+    if (!(go === 'back' || go === 'forward' || go === 'refresh' ||
+          go === 'reload')) {
       throw new Error('Invalid direction to go to: "' + go +
                       '" in the target "' + target + '".\n' +
                       JSON.stringify(command));

tasks/instructions/hasAttribute.js

@@ -0,0 +1,23 @@
+'use strict';
+
+module.exports = {
+  detect: function (command) {
+    return !!command.hasAttribute;
+  },
+
+  perform: function (grunt, target, client, command) {
+    const hasAttribute = command.hasAttribute,
+          selector = hasAttribute.selector,
+          name = hasAttribute.name,
+          expected = hasAttribute.value;
+    grunt.log.ok('Looking for attribute "' + name + '" with value "' +
+                 expected + '" at "' + selector + '".');
+    return client.getAttribute(selector, name)
+      .then(function (actual) {
+        if (actual != expected) {
+          throw new Error ('Value of attribute "' + name + '" at "' +
+            selector + '" was not "' + expected + '" but "' + actual + '".');
+        }
+      });
+  }
+};

tasks/instructions/hasClass.js

@@ -0,0 +1,28 @@
+'use strict';
+
+module.exports = {
+  detect: function (command) {
+    return !!command.hasClass;
+  },
+
+  perform: function (grunt, target, client, command) {
+    const hasClass = command.hasClass,
+          selector = hasClass.selector,
+          expected = hasClass.value || '',
+          expectedList = expected.split(/ +/);
+    grunt.log.ok('Looking for classes "' + expected + '" at "' +
+                 selector + '".');
+    return client.getAttribute(selector, 'class')
+      .then(function (actual) {
+        const actualList = (actual || '').split(/ +/);
+        if (!expectedList.some(function (expected) {
+              return expected.startsWith('!') ?
+                actualList.indexOf(expected.substr(1)) < 0 :
+                actualList.indexOf(expected) >= 0;
+            })) {
+          throw new Error ('Classes "' + expected +
+            '" were not found among "' + actual + '".at "' + selector + '".');
+        }
+      });
+  }
+};

tasks/instructions/hasInnerHtml.js

@@ -0,0 +1,22 @@
+'use strict';
+
+module.exports = {
+  detect: function (command) {
+    return !!command.hasInnerHtml;
+  },
+
+  perform: function (grunt, target, client, command) {
+    const hasInnerHtml = command.hasInnerHtml,
+          selector = hasInnerHtml.selector,
+          expected = hasInnerHtml.value;
+    grunt.log.ok('Comparing inner HTML at "' + selector + '" to "' +
+                 expected + '".');
+    return client.getHTML(selector, false)
+      .then(function (actual) {
+        if (actual != expected) {
+          throw new Error ('Inner HTML at "' + selector + '" was not "' +
+                           expected + '" but "' + actual + '".');
+        }
+      });
+  }
+};

tasks/instructions/hasOuterHtml.js

@@ -0,0 +1,22 @@
+'use strict';
+
+module.exports = {
+  detect: function (command) {
+    return !!command.hasInnhasOuterHtmlerHtml;
+  },
+
+  perform: function (grunt, target, client, command) {
+    const hasOuterHtml = command.hasOuterHtml,
+          selector = hasOuterHtml.selector,
+          expected = hasOuterHtml.value;
+    grunt.log.ok('Comparing outer HTML at "' + selector + '" to "' +
+                 expected + '".');
+    return client.getHTML(selector, true)
+      .then(function (actual) {
+        if (actual != expected) {
+          throw new Error ('Outer HTML at "' + selector + '" was not "' +
+                           expected + '" but "' + actual + '".');
+        }
+      });
+  }
+};

tasks/instructions/hasText.js

@@ -0,0 +1,22 @@
+'use strict';
+
+module.exports = {
+  detect: function (command) {
+    return !!command.hasText;
+  },
+
+  perform: function (grunt, target, client, command) {
+    const hasText = command.hasText,
+          selector = hasText.selector,
+          expected = hasText.value;
+    grunt.log.ok('Comparing text at "' + selector + '" to "' +
+                 expected + '".');
+    return client.getText(selector)
+      .then(function (actual) {
+        if (actual != expected) {
+          throw new Error ('Text at "' + selector + '" was not "' +
+                           expected + '" but "' + actual + '".');
+        }
+      });
+  }
+};