feat: Allow separate navigation, page interaction and saving snapshots

If you need to create multiple snapshots for a more complicated scenario
on an SPA, you will want to stay on the same page and do a couple of
actions. The objects in the `pages` array need only one of "url", "file"
and "wait" parameters to allow creating a sequence of commands.

Author: prantlf

Gruntfile.js

@@ -68,7 +68,7 @@ module.exports = function (grunt) {
         dest: 'test/snapshots'
       },
       'single-target.html': {
-        url: 'http://localhost:8881/test/pages/single-target.html',
+        url: 'http://localhost:8881/test/pages/single-target.html'
       },
       others: {
         pages: [
@@ -112,6 +112,22 @@ module.exports = function (grunt) {
             },
             file: 'no-doctype.html',
             url: 'http://localhost:8881/test/pages/no-doctype.html'
+          },
+          {
+            url: 'http://localhost:8881/test/pages/dynamic-multiple.html'
+          },
+          {
+            file: 'dynamic-first.html'
+          },
+          {
+            wait: '.second',
+            file: 'dynamic-second.html'
+          },
+          {
+            wait: '.third'
+          },
+          {
+            file: 'dynamic-third.html'
           }
         ]
       }
@@ -139,10 +155,6 @@ module.exports = function (grunt) {
   grunt.loadNpmTasks('grunt-selenium-standalone');
   grunt.loadTasks(coverage ? 'coverage/tasks' : 'tasks');
 
-  grunt.registerTask('default', coverage ?
-    ['jshint', 'clean', 'instrument', 'embedFonts', 'nodeunit',
-     'storeCoverage', 'makeReport'] :
-    ['jshint', 'clean:tests', 'embedFonts', 'nodeunit']);
   grunt.registerTask('default', coverage ? [
     'clean', 'eslint', 'instrument',
     'selenium_standalone:serverConfig:install',

README.md

@@ -131,8 +131,10 @@ If the sub-task contains a property `pages`, this property is supposed to point
 
 ### Parameters
 
+One of the `file`, `url` ans `wait` oarameters has to be present.
+
 #### file
-Type: `String` (mandatory)
+Type: `String`
 
 Name of the file to write the snapshot to.
 
@@ -143,8 +145,10 @@ Name of the file to write the snapshot to.
 }
 ```
 
+If it is omitted, the object will save no snashot. It can still change location or wait for some change.
+
 #### url
-Type: `String` (mandatory)
+Type: `String`
 
 URL to connect the web browser to for taking the snapshot.
 
@@ -155,6 +159,8 @@ URL to connect the web browser to for taking the snapshot.
 }
 ```
 
+If it is omitted, the object will reuse the previous location. It can wait for a further change and/or save another snapshot.
+
 #### options
 Type: `Object` (optional)
 
@@ -233,6 +239,38 @@ If the selector is prefixed by "!", the waiting waiting will stop, if the node d
 }
 ```
 
+If `wait` is omitted, the task will advance to another item without delay. It can still save a snapshot immediately.
+
+### Parameter Combinations
+
+The following array of objects within the `pages` parameter 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
+{
+  url: 'http://localhost/app'
+  file: 'initial.html'
+},
+{
+  wait: 500,
+  file: 'after-500ms.html'
+},
+{
+  wait: '#search',
+  file: 'form-ready.html'
+},
+{
+  wait: function (browser) {
+    return browser.click('#search')
+        .waitForExist('#results', 1000);
+  },
+  file: 'results-shown.html'
+}
+```
+
+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.
+
 ### Loading
 
 Load the plugin in `Gruntfile.js`:
@@ -292,7 +330,7 @@ grunt.initConfig({
       seleniumVersion: '3.7.1',
       seleniumDownloadURL: 'http://selenium-release.storage.googleapis.com',
       drivers: {
-        chrome: { // http://chromedriver.storage.googleapis.com/
+        chrome: {
           version: '2.33',
           arch: process.arch,
           baseURL: 'https://chromedriver.storage.googleapis.com'

tasks/html-dom-snapshot.js

@@ -34,9 +34,10 @@ module.exports = function (grunt) {
             dest: 'snapshots',
             force: false
           }),
+          target = this.target,
           pages = data.pages || [
             Object.assign({
-              file: this.target
+              file: target
             }, data)
           ],
           client = webdriverio.remote({
@@ -76,12 +77,18 @@ module.exports = function (grunt) {
     }
 
     function takeSnapshot(page) {
-      const url = page.url,
-            pageOptions = Object.assign({}, options, page.options || {});
-      grunt.verbose.writeln('Taking a snapshot of ' + url + '...');
+      const pageOptions = Object.assign({}, options, page.options || {}),
+            url = page.url,
+            file = page.file;
+      var wait = page.wait;
+      if (url) {
+        grunt.verbose.writeln('Taking a snapshot of ' + url + '...');
+      } else {
+        grunt.verbose.writeln('Preparing the next snapshot...');
+      }
       return client.setViewportSize(pageOptions.viewport)
         .then(function () {
-          return client.url(url);
+          return url && client.url(url);
         })
         .then(waitForContent)
         .then(function () {
@@ -90,9 +97,8 @@ module.exports = function (grunt) {
         .then(saveContent);
 
       function waitForContent() {
-        var wait = page.wait;
         if (!Array.isArray(wait)) {
-          wait = [wait];
+          wait = wait ? [wait] : [];
         }
         return wait.reduce(function (promise, wait) {
           return promise.then(function () {
@@ -114,21 +120,23 @@ module.exports = function (grunt) {
       }
 
       function saveContent(html) {
-        const dest = pageOptions.dest,
-              target = path.join(dest, page.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) {
-                if (error) {
-                  reject(error);
-                } else {
-                  resolve();
-                }
+        const dest = pageOptions.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) {
+                  if (error) {
+                    reject(error);
+                  } else {
+                    resolve();
+                  }
+                });
               });
             });
-          });
+        }
       }
     }
   });

test/pages/dynamic-multiple.html

@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+<head>
+<title>dynamic-multiple</title>
+<script>setTimeout(function () { document.body.classList.add('second');setTimeout(function () { document.body.classList.add('third') }, 100) }, 100)</script>
+</head>
+<body class="first"></body>
+</html>

test/test.js

@@ -65,5 +65,19 @@ exports['html-dom-snapshot'] = {
     const pages = readPages('no-doctype.html');
     test.equal(pages.expected, pages.actual, 'no-doctype.html');
     test.done();
+  },
+
+  'dynamic-multiple': function (test) {
+    const original = readPage('pages/dynamic-multiple.html'),
+          first = readPage('snapshots/dynamic-first.html'),
+          second = readPage('snapshots/dynamic-second.html'),
+          third = readPage('snapshots/dynamic-third.html');
+    var expected = original;
+    test.equal(expected, first, 'dynamic-first.html');
+    expected = original.replace('<body class="first">', '<body class="first second">');
+    test.equal(expected, second, 'dynamic-second.html');
+    expected = original.replace('<body class="first">', '<body class="first second third">');
+    test.equal(expected, third, 'dynamic-third.html');
+    test.done();
   }
 };