feat: Introduce the option "singleElementSelections" to enforce selectors mathing none or one element; never multiple ones

Author: prantlf

Gruntfile.js

@@ -338,6 +338,19 @@ module.exports = function (grunt) {
               value: '<div class="class" tabindex="0">Text</div>'
             }
           },
+          {
+            options: {
+              singleElementSelections: true
+            },
+            isExisting: 'select'
+          },
+          {
+            options: {
+              singleElementSelections: true,
+              force: true
+            },
+            isExisting: 'option'
+          },
           coverage ? { wait: 1 } : {
             focus: 'body',
             wait: function (browser) {

README.md

@@ -96,6 +96,7 @@ Default options support the most usual usage scenario:
     fileNumberSeparator: '.',
     hangOnError: false,
     snapshotOnError: '_last-error',
+    singleElementSelections: false,
     force: false
   },
   'google': {
@@ -221,6 +222,14 @@ 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.
 
+### singleElementSelections
+Type: `Boolean`
+Default value: false
+
+If set to `true`, it will enforce every selector match either one or none elements. If any selector matches multiple elements, the instruction will fail. Tests usually address just one element. This setting helps to uncover errors like checking `isFocus` for multiple elements, which has unpredictable results.
+
+This option can be set for the whole task or within a single command object.
+
 #### force
 Type: `Boolean`
 Default value: false

tasks/html-dom-snapshot.js

@@ -55,6 +55,7 @@ module.exports = grunt => {
         fileNumberSeparator: '.',
         hangOnError: false,
         snapshotOnError: '_last-error',
+        singleElementSelections: false,
         force: false,
         verbose: false
       })

tasks/instructions/addValue.js

@@ -1,16 +1,21 @@
 'use strict'
 
+const { checkSingleElement } = require('./utils/elements')
+
 module.exports = {
   detect: function (command) {
     return !!command.addValue
   },
 
-  perform: function (grunt, target, client, command) {
+  perform: async function (grunt, target, client, command, options) {
     const addValue = command.addValue
     const selector = addValue.selector
     const value = addValue.value
     grunt.output.writeln('Add "' + value + '" to value of "' +
                           selector + '".')
+    if (options.singleElementSelections) {
+      await checkSingleElement(client, selector)
+    }
     return client.$(selector)
       .then(element => element.addValue(value))
   }

tasks/instructions/clearValue.js

@@ -1,15 +1,18 @@
 'use strict'
 
-const { findElement } = require('./utils/elements')
+const { findElement, checkSingleElement } = require('./utils/elements')
 
 module.exports = {
   detect: function (command) {
     return !!command.clearValue
   },
 
-  perform: function (grunt, target, client, command) {
+  perform: async function (grunt, target, client, command, options) {
     const clearValue = command.clearValue
     grunt.output.writeln('Clear value of "' + clearValue + '".')
+    if (options.singleElementSelections) {
+      await checkSingleElement(client, clearValue)
+    }
     return findElement(client, clearValue)
       .then(element => client.elementClear(element))
   }

tasks/instructions/click.js

@@ -1,15 +1,18 @@
 'use strict'
 
-const { findElement } = require('./utils/elements')
+const { findElement, checkSingleElement } = require('./utils/elements')
 
 module.exports = {
   detect: function (command) {
     return !!command.click
   },
 
-  perform: function (grunt, target, client, command) {
+  perform: async function (grunt, target, client, command, options) {
     const click = command.click
     grunt.output.writeln('Click on "' + click + '".')
+    if (options.singleElementSelections) {
+      await checkSingleElement(client, click)
+    }
     return findElement(client, click)
       .then(element => client.elementClick(element))
   }

tasks/instructions/clickIfVisible.js

@@ -1,16 +1,19 @@
 'use strict'
 
-const { findElement } = require('./utils/elements')
+const { findElement, checkSingleElement } = require('./utils/elements')
 
 module.exports = {
   detect: function (command) {
     return !!command.clickIfVisible
   },
 
-  perform: function (grunt, target, client, command) {
+  perform: async function (grunt, target, client, command, options) {
     const clickIfVisible = command.clickIfVisible
     grunt.output.writeln('Checking visibility of "' + clickIfVisible + '"...')
     let clickable
+    if (options.singleElementSelections) {
+      await checkSingleElement(client, clickIfVisible)
+    }
     return findElement(client, clickIfVisible)
       .then(element => {
         clickable = element

tasks/instructions/elementSendKeys.js

@@ -1,25 +1,24 @@
 'use strict'
 
-const { findElement } = require('./utils/elements')
+const { findElement, checkSingleElement } = require('./utils/elements')
 
 module.exports = {
   detect: function (command) {
     return !!command.elementSendKeys
   },
 
-  perform: function (grunt, target, client, command) {
+  perform: async function (grunt, target, client, command, options) {
     const elementSendKeys = command.elementSendKeys
     const selector = elementSendKeys.selector
     let keys = elementSendKeys.keys || []
     let text = elementSendKeys.text || ''
-    // const separateKeys = Array.isArray(keys)
     const message = text
       ? 'Send text "' + text + '" to "' + selector + '".'
       : 'Send keys "' + keys.join('", "') + '" to "' + selector + '".'
-    // if (!separateKeys) {
-    //   keys = keys.split('')
-    // }
     grunt.output.writeln(message)
+    if (options.singleElementSelections) {
+      await checkSingleElement(client, selector)
+    }
     return findElement(client, selector)
       .then(element => client.elementSendKeys(element, text, keys))
   }

tasks/instructions/focus.js

@@ -6,14 +6,19 @@
 
 /* istanbul ignore next */
 
+const { checkSingleElement } = require('./utils/elements')
+
 module.exports = {
   detect: function (command) {
     return !!command.focus
   },
 
-  perform: function (grunt, target, client, command) {
+  perform: async function (grunt, target, client, command, options) {
     const focus = command.focus
     grunt.output.writeln('Focus "' + focus + '".')
+    if (options.singleElementSelections) {
+      await checkSingleElement(client, focus)
+    }
     return client.execute(function (selector) {
       var element = document.querySelector(selector)
       if (!element) {

tasks/instructions/hasAttribute.js

@@ -1,17 +1,22 @@
 'use strict'
 
+const { checkSingleElement } = require('./utils/elements')
+
 module.exports = {
   detect: function (command) {
     return !!command.hasAttribute
   },
 
-  perform: function (grunt, target, client, command) {
+  perform: async function (grunt, target, client, command, options) {
     const hasAttribute = command.hasAttribute
     const selector = hasAttribute.selector
     const name = hasAttribute.name
     const expected = hasAttribute.value
     grunt.log.ok('Looking for attribute "' + name + '" with value "' +
                  expected + '" at "' + selector + '".')
+    if (options.singleElementSelections) {
+      await checkSingleElement(client, selector)
+    }
     return client.$(selector)
       .then(element => element.getAttribute(name))
       .then(function (actual) {