feat: Make a snapshot and/or a screenshot in case of failure automatically

Use the new option `snapshogtOnError` to enable it and set the file name. Snapshots and screenshots need their directories specified for the failure snapshots.

Author: prantlf

Gruntfile.js

@@ -203,6 +203,24 @@ module.exports = function (grunt) {
                 })
             }
           },
+          {
+            scroll: {
+              selector: 'input',
+              offset: {
+                top: 0,
+                left: 0
+              }
+            },
+            clickIfVisible: 'input',
+            wait: function (browser) {
+              return browser.hasFocus('input')
+                .then(function (value) {
+                  if (value === false) {
+                    throw new Error('clickIfVisible on body failed')
+                  }
+                })
+            }
+          },
           {
             setValue: {
               selector: 'input',
@@ -272,11 +290,13 @@ module.exports = function (grunt) {
             isFocused: 'select',
             isVisible: 'select',
             isVisibleWithinViewport: 'select',
+            isSelected: 'select > option:last-child',
             isNotEnabled: 'input',
             isNotExisting: 'textarea',
             isNotFocused: 'input',
             isNotVisible: 'input',
             isNotVisibleWithinViewport: 'input',
+            isNotSelected: 'select > option:first-child',
             hasAttribute: {
               selector: 'input',
               name: 'disabled',
@@ -299,6 +319,17 @@ module.exports = function (grunt) {
               value: '<div class="class" tabindex="0">Text</div>'
             }
           },
+          {
+            clickIfVisible: 'select',
+            wait: function (browser) {
+              return browser.hasFocus('select')
+                .then(function (value) {
+                  if (value === false) {
+                    throw new Error('clickIfVisible on select failed')
+                  }
+                })
+            }
+          },
           {
             hasClass: {
               selector: 'div',
@@ -446,7 +477,8 @@ module.exports = function (grunt) {
       },
       'invalid-go': {
         options: {
-          force: true
+          force: true,
+          screenshots: 'test/screenshots'
         },
         pages: [
           {
@@ -519,7 +551,6 @@ module.exports = function (grunt) {
   grunt.loadTasks(coverage ? 'coverage/tasks' : 'tasks')
 
   const test = ['clean', 'standard',
-    'selenium_standalone:server:install',
     'selenium_standalone:server:start',
     'connect', 'html-dom-snapshot',
     'selenium_standalone:server:stop', 'nodeunit']

INSTRUCTIONS.md

@@ -677,7 +677,7 @@ Stops executing firther commands and fails current Grunt task with the specified
 ## file
 Type: `String`
 
-Name of the file to write the snapshot to. If it does not end with ".html" or ".htm", the extension ".html" will be appended to it.
+Name of the file to write the snapshot to. It will be put to lower-case before it is used. If it does not end with ".html" or ".htm", the extension ".html" will be appended to it.
 
 If writing screenshots is enabled, the same name will be used for the file with the screenshot; just without the extension ".html" or ".htm", if the file name ends to it, and with the extension ".png" appended to the file name instead.
 

README.md

@@ -92,6 +92,7 @@ Default options support the most usual usage scenario:
     fileNumberDigits: 3,
     fileNumberSeparator: '.',
     hangOnError: false,
+    snapshotOnError: '_last-error',
     force: false
   },
   'google': {
@@ -209,6 +210,12 @@ Default value: false
 
 If set to `true`, it will not abort the process in case of a failure. It is useful, if you want to investigate the situation on the screen right after an error occurred. If you encounter an error flip this flag and re-run the failing scenario. Once you are finished terminate the process or interrupt it by Ctrl+C.
 
+### snapshotOnError
+Type: `String`
+Default value: '_last-error'
+
+If set to a non-empty string, if will be used as a file name for an automatically taken snapshot and screenshot (if those are enabled), if the task execution fails.
+
 #### force
 Type: `Boolean`
 Default value: false

tasks/html-dom-snapshot.js

@@ -51,14 +51,18 @@ module.exports = grunt => {
         fileNumberDigits: 3,
         fileNumberSeparator: '.',
         hangOnError: false,
+        snapshotOnError: '_last-error',
         force: false
       })
       const target = this.target
       const pages = data.pages
-      const snapshots = options.dest
+      let snapshots = options.dest
+      const screenshots = options.screenshots
       const viewport = options.viewport
       const webdriver = options.webdriver
       const browserCapabilities = options.browserCapabilities
+      const hangOnError = options.hangOnError
+      const snapshotOnError = options.snapshotOnError
       const lastViewport = {
         width: viewport.width,
         height: viewport.height
@@ -83,6 +87,8 @@ module.exports = grunt => {
                       'Use "snapshots" with the same content.')
         options.snapshots = snapshots
         delete options.dest
+      } else {
+        snapshots = options.snapshots
       }
       // TODO: Remove this, as soon as the moveTo command is re-implemented.
       webdriver.deprecationWarnings = false
@@ -110,21 +116,29 @@ module.exports = grunt => {
               failed = true
               grunt.verbose.error(error.stack)
               grunt.log.error(error)
-              if (!options.hangOnError) {
+            })
+            .then(() => {
+              if (failed && snapshotOnError) {
+                return makeFailureSnapshotAndScreenshot()
+                  .then(() => true, () => false)
+              }
+            })
+            .then(() => {
+              if (failed && !hangOnError) {
                 return stop(false)
               }
             })
             .then(() => {
               if (failed) {
-                const warn = options.force || options.hangOnError ? grunt.log.warn : grunt.fail.warn
+                const warn = options.force || hangOnError ? grunt.log.warn : grunt.fail.warn
                 warn('Taking snapshots failed.')
-                if (options.hangOnError) {
+                if (hangOnError) {
                   warn('Letting the browser run for your investigation.\nTerminate this process or interrupt it by Ctrl+C, once you are finished.')
                 }
               }
             })
             .then(() => {
-              if (!(failed && options.hangOnError)) {
+              if (!hangOnError) {
                 done()
               }
             })
@@ -265,7 +279,7 @@ module.exports = grunt => {
           .keys(command)
           .forEach(key => {
             if (!(instructionKeys.includes(key) || additionalKeys.includes(key))) {
-              throw new Error('Unrecognized instruction: "' + key + '".')
+              throw new Error('Unrecognised instruction: "' + key + '".')
             }
           })
         if (!(commandInstructions.some(instruction => instruction.detected) || file)) {
@@ -294,19 +308,7 @@ module.exports = grunt => {
           }), viewportSet)
         .then(() => {
           if (file) {
-            if (snapshots && screenshots) {
-              increaseFileCount(file)
-              return performInstruction(
-                Promise.all([makeSnapshot(), makeScreenshot()]))
-            }
-            if (snapshots) {
-              increaseFileCount(file)
-              return performInstruction(makeSnapshot())
-            }
-            if (screenshots) {
-              increaseFileCount(file)
-              return performInstruction(makeScreenshot())
-            }
+            return makeSnapshotAndScreenshot()
           }
         })
 
@@ -318,6 +320,22 @@ module.exports = grunt => {
           return promise
         }
 
+        function makeSnapshotAndScreenshot () {
+          if (snapshots && screenshots) {
+            increaseFileCount(file)
+            return performInstruction(
+              Promise.all([makeSnapshot(), makeScreenshot()]))
+          }
+          if (snapshots) {
+            increaseFileCount(file)
+            return performInstruction(makeSnapshot())
+          }
+          if (screenshots) {
+            increaseFileCount(file)
+            return performInstruction(makeScreenshot())
+          }
+        }
+
         function makeSnapshot () {
           return client.getHTML('html')
                       .then(saveContent)
@@ -329,53 +347,19 @@ module.exports = grunt => {
         }
 
         function saveContent (html) {
-          let fileName = file.toLowerCase()
-          fileName = fileName.endsWith('.html') ||
-                     fileName.endsWith('.htm') ? file : file + '.html'
+          let fileName = makeSnapshotName(file)
           if (fileNumbering) {
             fileName = numberFileName(fileName, fileNumbering)
           }
-          fileName = join(snapshots, fileName)
-          grunt.log.ok('Write snapshot to "' + fileName + '".')
-          const directory = dirname(fileName)
-          return ensureDirectory(directory)
-            .then(() => new Promise((resolve, reject) =>
-              writeFile(fileName, commandOptions.doctype + html,
-                error => {
-                  if (error) {
-                    reject(error)
-                  } else {
-                    ++snapshotCount
-                    resolve()
-                  }
-                })
-            ))
+          return writeContent(html, snapshots, fileName, commandOptions)
         }
 
         function saveImage (png) {
-          let fileName = file.toLowerCase()
-          fileName = fileName.endsWith('.html')
-                     ? file.substr(0, file.length - 5)
-                     : fileName.endsWith('.htm')
-                     ? file.substr(0, file.length - 4) : file
+          let fileName = makeScreenshotName(file)
           if (fileNumbering) {
             fileName = numberFileName(fileName, fileNumbering)
           }
-          fileName = join(screenshots, fileName + '.png')
-          grunt.log.ok('Write screenshot to "' + fileName + '".')
-          const directory = dirname(fileName)
-          return ensureDirectory(directory)
-            .then(() => new Promise((resolve, reject) =>
-              writeFile(fileName, Buffer.from(png.value, 'base64'),
-                error => {
-                  if (error) {
-                    reject(error)
-                  } else {
-                    ++screenshotCount
-                    resolve()
-                  }
-                })
-            ))
+          return writeImage(png, screenshots, fileName)
         }
 
         function increaseFileCount (file) {
@@ -415,6 +399,89 @@ module.exports = grunt => {
         }
       }
 
+      function makeSnapshotName (fileName) {
+        fileName = fileName.toLowerCase()
+        return fileName.endsWith('.html') ||
+               fileName.endsWith('.htm') ? fileName : fileName + '.html'
+      }
+
+      function makeScreenshotName (fileName) {
+        fileName = fileName.toLowerCase()
+        return fileName.endsWith('.html')
+               ? fileName.substr(0, fileName.length - 5)
+               : fileName.endsWith('.htm')
+               ? fileName.substr(0, fileName.length - 4) : fileName
+      }
+
+      function makeFailureSnapshotAndScreenshot () {
+        if (snapshots && screenshots) {
+          return Promise.all([makeFailureSnapshot(), makeFailureScreenshot()])
+        }
+        if (snapshots) {
+          return makeFailureSnapshot()
+        }
+        if (screenshots) {
+          return makeFailureScreenshot()
+        }
+        return Promise.resolve()
+      }
+
+      function makeFailureSnapshot () {
+        return client.getHTML('html')
+                     .then(saveFailureContent)
+      }
+
+      function makeFailureScreenshot () {
+        return client.screenshot()
+                     .then(saveFailureImage)
+      }
+
+      function saveFailureContent (html) {
+        const fileName = makeSnapshotName(snapshotOnError)
+        return writeContent(html, snapshots, fileName, options)
+      }
+
+      function saveFailureImage (png) {
+        const fileName = makeScreenshotName(snapshotOnError)
+        return writeImage(png, screenshots, fileName)
+      }
+
+      function writeContent (html, snapshots, fileName, options) {
+        fileName = join(snapshots, fileName)
+        grunt.log.ok('Write snapshot to "' + fileName + '".')
+        const directory = dirname(fileName)
+        return ensureDirectory(directory)
+          .then(() => new Promise((resolve, reject) =>
+            writeFile(fileName, options.doctype + html,
+              error => {
+                if (error) {
+                  reject(error)
+                } else {
+                  ++snapshotCount
+                  resolve()
+                }
+              })
+          ))
+      }
+
+      function writeImage (png, screenshots, fileName) {
+        fileName = join(screenshots, fileName + '.png')
+        grunt.log.ok('Write screenshot to "' + fileName + '".')
+        const directory = dirname(fileName)
+        return ensureDirectory(directory)
+          .then(() => new Promise((resolve, reject) =>
+            writeFile(fileName, Buffer.from(png.value, 'base64'),
+              error => {
+                if (error) {
+                  reject(error)
+                } else {
+                  ++screenshotCount
+                  resolve()
+                }
+              })
+          ))
+      }
+
       function ensureArray (item) {
         if (item && !Array.isArray(item)) {
           item = [item]

test/pages/values.html

@@ -6,7 +6,7 @@
 <body>
   <select autofocus>
     <option value="1">One</option>
-    <option value="2">Two</option>
+    <option value="2" selected>Two</option>
   </select>
   <input disabled="disabled" style="display:none" type="text" value="test">
   <div class="class" tabindex="0">Text</div>

test/test.js

@@ -97,5 +97,11 @@ exports['html-dom-snapshot'] = {
     const snapshot = fs.existsSync('test/snapshots/abort.html')
     test.ok(!snapshot, 'abort.html')
     test.done()
+  },
+
+  'invalid-go': function (test) {
+    test.ok(fs.existsSync('test/snapshots/_last-error.html'), '_last-error.html')
+    test.ok(fs.existsSync('test/screenshots/_last-error.png'), '_last-error.png')
+    test.done()
   }
 }