feat: Introduce conditional if-then-else instructions

Author: prantlf

Gruntfile.js

@@ -344,6 +344,35 @@ module.exports = function (grunt) {
               value: '1'
             }
           },
+          {
+            if: {
+              hasClass: {
+                selector: 'div',
+                value: 'class none'
+              }
+            },
+            else: {
+              wait: function () {
+                throw new Error('executed else branch')
+              }
+            }
+          },
+          {
+            if: [{
+              hasClass: {
+                selector: 'div',
+                value: 'dummy'
+              }
+            }],
+            then: [{
+              wait: function () {
+                throw new Error('executed then branch')
+              }
+            }],
+            else: [{
+              wait: 1
+            }]
+          },
           {
             setViewport: {
               width: 768,

INSTRUCTIONS.md

@@ -2,6 +2,7 @@
 
 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:
 
+- [if-then-else](#if-then-else)
 - [setViewport](#setviewport)
 - [url](#url)
 - [go](#go)
@@ -36,6 +37,42 @@ One of the instructions has to be present in every command. These properties are
 - [abort](#abort)
 - [file](#file)
 
+## if-then-else
+
+Conditional command consisting of two or three three instructions, which each points to a sub-command or to an array of sub-commands to perform:
+
+### if
+Type: `Object` | `Array` (mandatory)
+
+### then
+Type: `Object` | `Array` (optional)
+
+### else
+Type: `Object` | `Array` (optional)
+
+At first the sub-commands from the `if` instruction are performed. If they succeed, the execution continues with sub-sommands from the `then` instruction. If they fail, the execution continues with sub-sommands from the `else` instruction. The success or failure of the whole conditional command will depend on either of `then` and `else` instructions, which are executed. The success or failure of the `if` instruction decides only the following condition branch.
+
+```js
+{
+  url: 'https://google.com',
+  wait: '#lst-ib',
+  if: {
+    hasAttribute: {
+      selector: '#lst-ib',
+      name: 'autocomplete',
+      value: 'off'
+    }
+  },
+  then: {
+    setValue: {
+      selector: '#lst-ib',
+      value: 'autocomplete is off'
+    }
+  },
+  file: 'google'
+}
+```
+
 #### setViewport
 Type: `Object`
 

README.md

@@ -546,7 +546,7 @@ your code using Grunt.
 
 ## Release History
 
- * 2018-11-26  [v2.0.0]  Use headless Chrome instead of PhantomJS by default
+ * 2018-11-26  [v2.0.0]  Use headless Chrome instead of PhantomJS by default, introduce conditional if-then-else instructions
  * 2018-05-14  [v1.3.0]  Allow saving snapshots to sub-directories, file numbering per-directory, add `scroll` instruction
  * 2018-05-11  [v1.2.0]  Introduce delay after every instruction to be able to visually follow the actions when debugging
  * 2018-03-29  [v1.1.0]  Allow specifying all initialization parameters supported by WebdriverIO

tasks/html-dom-snapshot.js

@@ -96,7 +96,7 @@ module.exports = grunt => {
             .then(() => nodeCleanup(stop))
             .then(setViewportSize)
             .then(gatherCommands)
-            .then(performCommands)
+            .then(performConditionalCommands)
             .then(() => {
               grunt.log.ok(commands.length + ' ' +
                   grunt.util.pluralize(commands.length, 'command/commands') +
@@ -130,12 +130,9 @@ module.exports = grunt => {
       }
 
       function gatherCommands () {
-        let scenarios = data.scenarios
+        let scenarios = ensureArray(data.scenarios)
         commands = data.commands || pages
         if (scenarios) {
-          if (!Array.isArray(scenarios)) {
-            scenarios = [scenarios]
-          }
           const currentDirectory = process.cwd()
           commands = scenarios
             .reduce((scenarios, scenario) =>
@@ -157,11 +154,6 @@ module.exports = grunt => {
         }
       }
 
-      function performCommands () {
-        return commands.reduce((promise, command) =>
-          promise.then(() => performCommand(command)), Promise.resolve())
-      }
-
       function setViewportSize () {
         grunt.verbose.writeln('Resize viewport to ' + lastViewport.width +
                               'x' + lastViewport.height + '.')
@@ -179,6 +171,43 @@ module.exports = grunt => {
           }))
       }
 
+      function performConditionalCommands (subCommands) {
+        return (subCommands || commands).reduce((promise, command) =>
+          promise.then(() => performConditionalCommand(command)), Promise.resolve())
+      }
+
+      function performConditionalCommand (command) {
+        const ifCommands = ensureArray(command.if)
+        if (!ifCommands) {
+          return performCommand(command)
+        }
+        grunt.verbose.writeln('Testing a condition.')
+        const promise = performCommands(ifCommands)
+          .then(() => performConditionalBranch(command.then, true))
+          .catch(() => performConditionalBranch(command.else, false))
+        promise.then(logEnd, logEnd)
+        return promise
+
+        function logEnd () {
+          grunt.verbose.writeln('The conditional command ended.')
+        }
+      }
+
+      function performConditionalBranch (branch, result) {
+        const commands = ensureArray(branch)
+        grunt.verbose.writeln('The condition evaluated to ' + result + '.')
+        if (commands) {
+          grunt.verbose.writeln('Continuing with the conditional branch.')
+          return performConditionalCommands(commands)
+        }
+        return Promise.resolve()
+      }
+
+      function performCommands (subCommands) {
+        return (subCommands || commands).reduce((promise, command) =>
+          promise.then(() => performCommand(command)), Promise.resolve())
+      }
+
       function performCommand (command) {
         const commandOptions = Object.assign({
           lastViewport: lastViewport
@@ -350,5 +379,12 @@ module.exports = grunt => {
           return fileName
         }
       }
+
+      function ensureArray (item) {
+        if (item && !Array.isArray(item)) {
+          item = [item]
+        }
+        return item
+      }
     })
 }