chore: Upgrade WebdriverIO to the version 5 and adapt the task to stay compatible

chore: Upgrade other dependencies and require Node.js 8 or newer
feat: Allow enabling of the "verbose" logging for this task only
feat: Add a new instruction "elementSendKeys" for sending keys to a specific element

BREAKING CHANGE: Upgraded WebdriverIO 5 and dropped support of Node.js 7 and older.

Although the only broken instruction is `scroll`, which does not support the parameter `offset` any more, th eupgraded dependencies changed a lot and you wil lneed to check if your existing tests sill work.

Author: prantlf

.ncurc.yml

@@ -65,9 +65,9 @@ module.exports = function (grunt) {
       options: {
         verbose: true,
         webdriver: {
-          desiredCapabilities: {
+          capabilities: {
             browserName: 'chrome',
-            chromeOptions: {
+            'goog:chromeOptions': {
               args: ['--headless', '--no-sandbox']
             }
           }
@@ -123,7 +123,8 @@ module.exports = function (grunt) {
           {
             url: 'http://localhost:8881/test/pages/dynamic-custom.html',
             wait: function (browser) {
-              return browser.waitForExist('.dynamic', 1000)
+              return browser.$('.dynamic')
+                .then(element => element.waitForExist(1000))
             },
             file: 'dynamic-custom'
           },
@@ -196,7 +197,8 @@ module.exports = function (grunt) {
             moveCursor: 'input',
             click: 'input',
             wait: function (browser) {
-              return browser.hasFocus('input')
+              return browser.$('input')
+                .then(element => element.isFocused())
                 .then(function (value) {
                   if (value !== true) {
                     throw new Error('click failed')
@@ -205,15 +207,11 @@ module.exports = function (grunt) {
             }
           },
           {
-            scroll: {
-              offset: {
-                top: 0,
-                left: 0
-              }
-            },
+            scroll: 'body',
             clickIfVisible: 'input',
             wait: function (browser) {
-              return browser.hasFocus('input')
+              return browser.$('input')
+                .then(element => element.isFocused())
                 .then(function (value) {
                   if (value === false) {
                     throw new Error('clickIfVisible on body failed')
@@ -227,7 +225,8 @@ module.exports = function (grunt) {
               value: 'Hi'
             },
             wait: function (browser) {
-              return browser.getValue('input')
+              return browser.$('input')
+                .then(element => element.getValue())
                 .then(function (value) {
                   if (value !== 'Hi') {
                     throw new Error('setValue failed')
@@ -241,7 +240,8 @@ module.exports = function (grunt) {
               value: ' there!'
             },
             wait: function (browser) {
-              return browser.getValue('input')
+              return browser.$('input')
+                .then(element => element.getValue())
                 .then(function (value) {
                   if (value !== 'Hi there!') {
                     throw new Error('addValue failed')
@@ -252,7 +252,8 @@ module.exports = function (grunt) {
           {
             clearValue: 'input',
             wait: function (browser) {
-              return browser.getValue('input')
+              return browser.$('input')
+                .then(element => element.getValue())
                 .then(function (value) {
                   if (value !== '') {
                     throw new Error('clearValue failed')
@@ -264,18 +265,36 @@ module.exports = function (grunt) {
             click: 'input',
             keys: 'test',
             wait: function (browser) {
-              return browser.getValue('input')
+              return browser.$('input')
+                .then(element => element.getValue())
                 .then(function (value) {
                   if (value !== 'test') {
                     throw new Error('sending text failed')
                   }
                 })
             }
           },
+          {
+            clearValue: 'input',
+            elementSendKeys: {
+              selector: 'input',
+              text: 'Test'
+            },
+            wait: function (browser) {
+              return browser.$('input')
+                .then(element => element.getValue())
+                .then(function (value) {
+                  if (value !== 'Test') {
+                    throw new Error('sending text to an element failed')
+                  }
+                })
+            }
+          },
           {
             keys: ['Home', 'Delete'],
             wait: function (browser) {
-              return browser.getValue('input')
+              return browser.$('input')
+                .then(element => element.getValue())
                 .then(function (value) {
                   if (value !== 'est') {
                     throw new Error('sending key strokes failed', value)
@@ -322,7 +341,8 @@ module.exports = function (grunt) {
           coverage ? { wait: 1 } : {
             focus: 'body',
             wait: function (browser) {
-              return browser.hasFocus('body')
+              return browser.$('body')
+                .then(element => element.isFocused())
                 .then(function (value) {
                   if (value !== false) {
                     throw new Error('focus on body failed')
@@ -333,7 +353,8 @@ module.exports = function (grunt) {
           {
             clickIfVisible: 'input',
             wait: function (browser) {
-              return browser.hasFocus('input')
+              return browser.$('input')
+                .then(element => element.isFocused())
                 .then(function (value) {
                   if (value !== false) {
                     throw new Error('clickIfVisible on invisible input failed')
@@ -501,9 +522,9 @@ module.exports = function (grunt) {
       },
       'invalid-file': {
         options: {
-          browserCapabilities: {
+          capabilities: {
             browserName: 'chrome',
-            chromeOptions: {
+            'goog:chromeOptions': {
               args: ['--headless', '--no-sandbox']
             }
           },

Gruntfile.js

@@ -18,7 +18,9 @@ One of the instructions has to be present in every command. These properties are
 - [selectOptionByValue](#selectoptionbyvalue)
 - [moveCursor](#movecursor)
 - [click](#click)
+- [clickIfVisible](#clickIfVisible)
 - [keys](#keys)
+- [elementSendKeys](#elementSendKeys)
 - [wait](#wait)
 - [hasAttribute](#hasattribute)
 - [hasClass](#hasclass)
@@ -365,6 +367,19 @@ Moves the mouse cursor to an element with the specified selector. If an object i
 }
 ```
 
+## clickIfVisible
+Type: `String`
+
+Triggers a click event on an element with the specified selector, if the elment is visible. Otherwise continues silently.
+
+```js
+{
+  url: 'https://google.com',
+  clickIfVisible: 'input[name=btnK]',
+  file: 'google'
+}
+```
+
 ## click
 Type: `String`
 
@@ -392,6 +407,26 @@ Sends either a text (string) typed by keys, or single keystrokes (array) to the
 }
 ```
 
+## elementSendKeys
+Type: `Object`
+
+Sends either a text (string), or single keystrokes (array) to an element in the browser. The object should contain the following properties:
+
+* `selector` - `String` - selector of the element to send the keys or text to.
+* `text` - `String` - the text to send to the element.
+* `keys` - `Array<String>` - the keystrokes to send to the element.
+
+```js
+{
+  url: 'https://google.com',
+  elementSendKeys: {
+    selector: 'input[name=btnK]',
+    text: 'test'
+  },
+  file: 'google'
+}
+```
+
 ## wait
 Type: `Number` | `String` | `Function` | `Array` (optional)
 
@@ -433,7 +468,8 @@ If the selector is prefixed by the exclamation mark ("!"), the waiting waiting w
 {
   url: 'https://google.com',
   wait: function (browser) {
-    return browser.waitForExist('#footer', 1000);
+    return browser.$('#footer')
+      .then(element => element.waitForExist(1000));
   },
   file: 'google'
 }

INSTRUCTIONS.md

@@ -0,0 +1,125 @@
+# Migration from Earlier Versions
+
+Increasing the major version means a breaking change in existing functionality, or at least deprecation of a feature, which has been replaced by an alternative. When you upgrade `grunt-html-dom-snapshot` to a higher major version, you might ned to update your configuration or even the task commands.
+
+I recommend you upgrading `grunt-html-dom-snapshot` regularly. Functionality and security bugs are looked for and fixed in latest versions, not in old and thus little used ones.
+
+# Upgrade Instructions
+
+- [3 to 4](#3-to-4)
+- [2 to 3](#2-to-3)
+- [1 to 2](#1-to-2)
+- [0 to 1](#0-to-1)
+
+## 3 to 4
+
+Although you may not notice any breaking changes, **v4 upgraded to [WebdriverIO] 5 and dropped support of [Node.js] older than 8**. You should upgrade Node.js in your environment and check, that everything still works.
+
+[WebdriverIO] overhauled its API, which meant adapting each instruction available in `grunt-html-dom-snapshot`. They all remained compatible, except for:
+
+* [scroll](INSTRUCTIONS.md#scroll) does not support the `offset` parameter any more. Remove it. Scrolling will be performed to the center of the element.
+* [isVisible](INSTRUCTIONS.md#isvisible), [isNotVisible](INSTRUCTIONS.md#isnotvisible) and [clickIfVisible](INSTRUCTIONS.md#clickIfVisible) use the function [isElementDisplayed] which should work in the same way like the removed [isVisible], but you should still check if your visibility checks still work.
+
+## 2 to 3
+
+You will probably not notice any breaking changes in your scripts during this upgrade.
+
+**Unrecognised instructions are forbidden in v3.** They hid typos in instruction that you wanted to execute. If you put foreign keys to the task commands, you will have to remove them and use comments instead, for example.
+
+Old code:
+
+```json
+{
+  "doNotForget": "focus the other elements later",
+  "click": "input",
+  "file": "focused-input"
+}
+```
+
+New code:
+
+```json
+{
+  // TODO: Focus the other elements later.
+  "click": "input",
+  "file": "focused-input"
+}
+```
+
+See the [release notes for v3] for more information.
+
+## 1 to 2
+
+**v2 does not use PhantomJS by default any more.** The development has been stopped in favour of the headless mode introduced by Chrome and Firefox. You can still enable the webdriver for PhantomJS explicitly. However, it will be used less and less in the world and the quality of its support will deteriorate. Plan switching to the headless mode of Chrome and check, that your tests still work. If you did not use PhantomJS-specific API, you would only adapt the task configuration and should not notice any breaking changes in your scripts.
+
+Old configuration:
+
+```js
+'selenium_standalone': {
+  serverConfig: {
+    seleniumVersion: '3.7.1',
+    seleniumDownloadURL: 'http://selenium-release.storage.googleapis.com',
+    drivers: {
+      phantomjs: {
+        version: '2.1.1'
+      }
+    }
+  }
+},
+'html-dom-snapshot': {
+  options: {
+    webdriver: {
+      capabilities: {
+        browserName: 'phantomjs'
+      }
+    }
+  }
+}
+```
+
+New configuration:
+
+```js
+'selenium_standalone': {
+  serverConfig: {
+    seleniumVersion: '3.141.5',
+    seleniumDownloadURL: 'http://selenium-release.storage.googleapis.com',
+    drivers: {
+      chrome: {
+        version: '77.0.3865.40',
+        arch: process.arch,
+        baseURL: 'https://chromedriver.storage.googleapis.com'
+      }
+    }
+  }
+},
+'html-dom-snapshot': {
+  options: {
+    webdriver: {
+      capabilities: {
+        browserName: 'chrome',
+        'goog:chromeOptions': {
+          args: ['--headless']
+        }
+      }
+    }
+  }
+}
+```
+
+See the [release notes for v2] for more information.
+
+## 0 to 1
+
+**v1 runs only in Node.js 6 or newer.** Node.js 4 reeached its end-of-life and does not use PhantomJS by default any more. The development has been stopped in favour of the headless mode introduced by Chrome and Firefox. You can still enable the webdriver for PhantomJS explicitly. However, it will be used less and less in the world and the quality of its support will deteriorate. Plan switching to the headless mode of Chrome and check, that your tests still work. If you did not use PhantomJS-specific API, you would only adapt the task configuration and should not notice any breaking changes in your scripts.
+
+See the [release notes for v1] for more information.
+
+[WebdriverIO]: http://webdriver.io/
+[Node.js]: https://nodejs.org
+[isElementDisplayed]: https://webdriver.io/docs/api/webdriver.html#iselementdisplayed
+[isVisible]: http://v4.webdriver.io/api/state/isVisible.html
+[release notes for v4]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v4.0.0
+[release notes for v3]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v3.0.0
+[release notes for v2]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v2.0.0
+[release notes for v1]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v1.0.0