fix: Rename the property "pages" in a sub-task to "commands"

* Recognize "pages" too for compatibility.
* Warn about deprecated property if "pages" is used.

Author: prantlf

Gruntfile.js

@@ -71,7 +71,7 @@ module.exports = function (grunt) {
         url: 'http://localhost:8881/test/pages/single-target.html'
       },
       others: {
-        pages: [
+        commands: [
           {
             file: 'static.html',
             url: 'http://localhost:8881/test/pages/static.html'
@@ -135,17 +135,20 @@ module.exports = function (grunt) {
         options: {
           force: true
         },
-        pages: [
+        commands: [
           {}
         ]
       },
       'invalid-file': {
         options: {
           force: true
         },
-        '//': {
-          url: 'http://localhost:8881'
-        }
+        pages: [
+          {
+            url: 'http://localhost:8881',
+            file: '//'
+          }
+        ]
       },
       'invalid-dest': {
         options: {

README.md

@@ -149,12 +149,12 @@ File names for snapshots can be used as sub-task names. Separate sub-tasks initi
 }
 ```
 
-If the sub-task contains a property `pages`, this property is supposed to point to an array of commands - navigations and other browser interactions, waiting for browser states and making snapshots. They share the same instance of the webdriver, which improves the performance:
+If the sub-task contains a property `commands`, this property is supposed to point to an array of command objects - navigations and other browser interactions, waiting for browser states and making snapshots. They share the same instance of the webdriver, which improves the performance:
 
 ```js
 'html-dom-snapshot': {
   all: {
-    pages: [
+    commands: [
       {
         file: 'google.html',
         url: 'https://google.com'
@@ -282,7 +282,7 @@ If `wait` is omitted, the task will advance to another item without delay. It ca
 
 ### Parameter Combinations
 
-The following array of commands within the `pages` property will change location, make a snapshot immediately to save the server-side pre-rendered content, then another one to see the progress after the first 500 milliseconds and yet another one, once the search form is ready. Then it submits the form by clicking on the "Search" button, waits until the search results are displayed and makes one final snapshot.
+The following array of commands within the `commands` property will change location, make a snapshot immediately to save the server-side pre-rendered content, then another one to see the progress after the first 500 milliseconds and yet another one, once the search form is ready. Then it submits the form by clicking on the "Search" button, waits until the search results are displayed and makes one final snapshot.
 
 ```js
 {
@@ -308,7 +308,7 @@ The following array of commands within the `pages` property will change location
 
 Other Grunt tasks can run later and validate, compare or otherwise process the page content in different stages of the "Search" scenario.
 
-Navigating to other location, interacting with the page, waiting for some effect to show and saving a snapshot can be divided to different objects in the `pages` array. However, at least One of the `file`, `url` ans `wait` oarameters has to be present in ever object.
+Navigating to other location, interacting with the page, waiting for some effect to show and saving a snapshot can be divided to different objects in the `commands` array. However, at least One of the `file`, `url` ans `wait` oarameters has to be present in ever object.
 
 When the commands become too many, you can divide them per page or per other criterion, which corresponds with a scenario and load them from separate modules:
 
@@ -326,7 +326,7 @@ The module for Addressbook would look like this:
 ```js
 module.exports = {
   options: {...},
-  pages: [
+  commands: [
     {
       url: 'https://localhost/addressbook'
       wait: '#addressbook.complete'

tasks/html-dom-snapshot.js

@@ -35,34 +35,47 @@ module.exports = function (grunt) {
             force: false
           }),
           target = this.target,
-          pages = data.pages || [
+          pages = data.pages;
+    if (pages) {
+      grunt.log.warn('The property "pages" is deprecated. ' +
+          'Use "commands" with the same content.');
+    }
+    const commands = data.commands || pages || [
             Object.assign({
               file: target
             }, data)
           ],
           client = webdriverio.remote({
             desiredCapabilities: options.browserCapabilities
           });
+    var urlCount = 0,
+        fileCount = 0;
 
-      client.init()
-            .then(function () {
-              return pages.reduce(function (promise, page) {
-                return promise.then(function () {
-                  return takeSnapshot(page);
-                });
-              }, Promise.resolve());
-            })
-            .then(function () {
-              grunt.log.ok(pages.length + ' snapshot(s) created.');
-              return client.end();
-            })
-            .catch(function (error) {
-              grunt.verbose.error(error.stack);
-              grunt.log.error(error);
-              const warn = options.force ? grunt.log.warn : grunt.fail.warn;
-              warn('Taking snapshot(s) failed.');
-            })
-            .then(done);
+    client.init()
+          .then(function () {
+            return commands.reduce(function (promise, command) {
+              return promise.then(function () {
+                return performCommand(command);
+              });
+            }, Promise.resolve());
+          })
+          .then(function () {
+            grunt.log.ok(commands.length + ' ' +
+                grunt.util.pluralize(commands.length, 'comand/comands') +
+                ' performed, ' + urlCount + ' ' +
+                grunt.util.pluralize(urlCount, 'page/pages') +
+                ' visited, ' + fileCount + ' ' +
+                grunt.util.pluralize(fileCount, 'file/files') +
+                ' written.');
+            return client.end();
+          })
+          .catch(function (error) {
+            grunt.verbose.error(error.stack);
+            grunt.log.error(error);
+            const warn = options.force ? grunt.log.warn : grunt.fail.warn;
+            warn('Taking snapshots failed.');
+          })
+          .then(done);
 
     function ensureDirectory(name) {
       return new Promise(function (resolve, reject) {
@@ -76,21 +89,23 @@ module.exports = function (grunt) {
       });
     }
 
-    function takeSnapshot(page) {
-      const pageOptions = Object.assign({}, options, page.options || {}),
-            url = page.url,
-            file = page.file;
-      var wait = page.wait;
+    function performCommand(command) {
+      const commandOptions = Object.assign({}, options, command.options || {}),
+            url = command.url,
+            file = command.file;
+      var wait = command.wait;
       if (url) {
         grunt.verbose.writeln('Taking a snapshot of ' + url + '...');
+        ++urlCount;
       } else {
         if (!(file || wait)) {
           throw new Error('Missing parameters "url", "file" or "wait" ' +
               'in the target "' + target + '".');
         }
         grunt.verbose.writeln('Preparing the next snapshot...');
       }
-      return client.setViewportSize(pageOptions.viewport)
+
+      return client.setViewportSize(commandOptions.viewport)
         .then(function () {
           return url && client.url(url);
         })
@@ -111,9 +126,9 @@ module.exports = function (grunt) {
             } else if (typeof wait === 'string') {
               if (wait.charAt(0) === '!') {
                 return client.waitForExist(wait.substr(1).trim(),
-                    pageOptions.selectorTimeout, true);
+                    commandOptions.selectorTimeout, true);
               }
-              return client.waitForExist(wait, pageOptions.selectorTimeout);
+              return client.waitForExist(wait, commandOptions.selectorTimeout);
             } else if (typeof wait === 'number') {
               return new Promise(function (resolve) {
                 setTimeout(resolve, wait);
@@ -124,17 +139,18 @@ module.exports = function (grunt) {
       }
 
       function saveContent(html) {
-        const dest = pageOptions.dest;
+        const dest = commandOptions.dest;
         if (file) {
           const target = path.join(dest, file);
           grunt.verbose.writeln('Writing the snapshot to ' + target + '...');
           return ensureDirectory(dest)
             .then(function () {
               return new Promise(function (resolve, reject) {
-                fs.writeFile(target, pageOptions.doctype + html, function (error) {
+                fs.writeFile(target, commandOptions.doctype + html, function (error) {
                   if (error) {
                     reject(error);
                   } else {
+                    ++fileCount;
                     resolve();
                   }
                 });