fix: Report unknown instructions as errors

BREAKING CHANGE: If you include a key in your command object, which is not recognized as an instruction or other known key (file, options), the task execution will fail.

Earlier you could put any key to a command object. You could use it as a comment or to store any other data there. Unfortunately, it lead to mistakes like typos in instruction names, which were  difficult to detect. From now on, only recognized keys  are allowed to appear in commands. You can use JavaScript comments to explain what a particular command or instruction does in your scenario.

Author: prantlf

Gruntfile.js

@@ -277,10 +277,10 @@ module.exports = function (grunt) {
             isNotFocused: 'input',
             isNotVisible: 'input',
             isNotVisibleWithinViewport: 'input',
-            hasAtribute: {
+            hasAttribute: {
               selector: 'input',
               name: 'disabled',
-              value: 'disabled'
+              value: 'true'
             },
             hasValue: {
               selector: 'input',
@@ -396,6 +396,14 @@ module.exports = function (grunt) {
           {}
         ]
       },
+      'invalid-instruction': {
+        options: {
+          force: true
+        },
+        commands: [
+          {invalid: {}}
+        ]
+      },
       'invalid-file': {
         options: {
           browserCapabilities: {

README.md

@@ -263,7 +263,7 @@ You can use sub-tasks, `commands` and `scenarios` to structure your code and exe
 
 ### Instructions
 
-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:
+One of the [instructions] has to be present in every command, otherwise its execution will fail. If you include a key in your command object, which is not recognised as an instruction or other known key (`file`, `options`), the execution will fail too. The following instructions are recognised (and their effect is executed) in the order, in which they are listed below:
 
 * [setViewport](INSTRUCTIONS.md#setviewport)
 * [url](INSTRUCTIONS.md#url)
@@ -597,6 +597,7 @@ your code using Grunt.
 
 ## Release History
 
+ * 2019-07-20  [v3.0.0]  Report unrecognised instructions as errors
  * 2019-07-08  [v2.2.0]  Optionally hang the browser in case of failure to be able to inspect the web page in developer tools
  * 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
@@ -642,6 +643,7 @@ Licensed under the MIT license.
 [grunt-reg-viz]: https://github.com/prantlf/grunt-reg-viz
 [grunt-selenium-standalone]: https://github.com/zs-zs/grunt-selenium-standalone
 [keyboard key identifiers]: https://w3c.github.io/webdriver/webdriver-spec.html#keyboard-actions
+[v3.0.0]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v3.0.0
 [v2.2.0]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v2.2.0
 [v2.0.0]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v2.0.0
 [v1.3.0]: https://github.com/prantlf/grunt-html-dom-snapshot/releases/tag/v1.3.0

tasks/html-dom-snapshot.js

@@ -4,7 +4,10 @@ const {writeFile} = require('fs')
 const pad = require('pad-left')
 const {basename, dirname, isAbsolute, join} = require('path')
 const mkdirp = require('mkdirp')
-const instructions = [
+// Instructions are listed explicitly here to ensure their right execution
+// order in a command object. In this order they will be looked for and
+// executed.
+const instructionKeys = [
   'setViewport', 'url', 'go', 'scroll', 'clearValue', 'setValue', 'addValue',
   'selectOptionByIndex', 'selectOptionByValue', 'moveCursor',
   'click', 'clickIfVisible', 'keys', 'wait', 'hasAttribute', 'hasClass', 'hasValue',
@@ -13,7 +16,10 @@ const instructions = [
   'isVisibleWithinViewport', 'isNotEnabled', 'isNotExisting',
   'isNotFocused', 'isNotSelected', 'isNotVisible',
   'isNotVisibleWithinViewport', 'abort'
-].map(instruction => require('./instructions/' + instruction))
+]
+const instructions = instructionKeys.map(instruction =>
+  require('./instructions/' + instruction))
+const additionalKeys = ['file', 'options']
 const directoryCounts = {}
 let fileCount = 0
 
@@ -255,6 +261,13 @@ module.exports = grunt => {
         } else {
           snapshots = commandOptions.snapshots
         }
+        Object
+          .keys(command)
+          .forEach(key => {
+            if (!(instructionKeys.includes(key) || additionalKeys.includes(key))) {
+              throw new Error('Unrecognized instruction: "' + key + '".')
+            }
+          })
         if (!(commandInstructions.some(instruction => instruction.detected) || file)) {
           throw new Error('Missing instruction in the command ' +
                           'in the target "' + target + '".\n' +