refactor(locators): moves scope in locators to last argument

scope defaults to document, and is an optional argument so now be moved to the
end. Came up from debugging and trying to use
window.clientSideScripts.findInputs('username'); which failed. Refactored to
match original intent.

BREAKING CHANGE: anything relying on clientsidescripts should no longer pass
    element scope as first argument.

    Before:

    window.clientSideScripts.findInputs(document, 'username');

    After:

    window.clientSideScripts.findInputs(document, 'username');

    Also, any custom locators using addLocator will now break since the
    arguments order has chnaged. To migrate the code follow the example below:

    Before:

    var findMenuItem = function() {
      var domScope = arguments[0];
      var myArg = arguments[1];
      // balh blah blah
    };
    by.addLocator('menuItem', findMenuItem);

    After:

    var findMenuItem = function() {
      var myArg = arguments[0];
      var domScope = arguments[1];
      // balh blah blah
    };
    by.addLocator('menuItem', findMenuItem);

Closes #497

lib/clientsidescripts.js

@@ -30,14 +30,14 @@ clientSideScripts.waitForAngular = function() {
 /**
  * Find a list of elements in the page by their angular binding.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The binding, e.g. {{cat.name}}.
+ * arguments[0] {string} The binding, e.g. {{cat.name}}.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The elements containing the binding.
  */
 clientSideScripts.findBindings = function() {
-  var using = arguments[0] || document;
-  var binding = arguments[1];
+  var binding = arguments[0];
+  var using = arguments[1] || document;
   var bindings = using.getElementsByClassName('ng-binding');
   var matches = [];
   for (var i = 0; i < bindings.length; ++i) {
@@ -57,17 +57,17 @@ clientSideScripts.findBindings = function() {
  * Always returns an array of only one element for plain old ng-repeat.
  * Returns an array of all the elements in one segment for ng-repeat-start.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The text of the repeater, e.g. 'cat in cats'.
- * arguments[2] {number} The row index.
+ * arguments[0] {string} The text of the repeater, e.g. 'cat in cats'.
+ * arguments[1] {number} The row index.
+ * arguments[2] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The row of the repeater, or an array of elements
  *     in the first row in the case of ng-repeat-start.
  */
  clientSideScripts.findRepeaterRows = function() {
-  var using = arguments[0] || document;
-  var repeater = arguments[1];
-  var index = arguments[2];
+  var repeater = arguments[0];
+  var index = arguments[1];
+  var using = arguments[2] || document;
 
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
   var rows = [];
@@ -109,14 +109,14 @@ clientSideScripts.findBindings = function() {
  /**
  * Find all rows of an ng-repeat.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The text of the repeater, e.g. 'cat in cats'.
+ * arguments[0] {string} The text of the repeater, e.g. 'cat in cats'.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} All rows of the repeater.
  */
  clientSideScripts.findAllRepeaterRows = function() {
-  var using = arguments[0] || document;
-  var repeater = arguments[1];
+  var repeater = arguments[0];
+  var using = arguments[1] || document;
 
   var rows = [];
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
@@ -152,19 +152,19 @@ clientSideScripts.findBindings = function() {
 /**
  * Find an element within an ng-repeat by its row and column.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The text of the repeater, e.g. 'cat in cats'.
- * arguments[2] {number} The row index.
- * arguments[3] {string} The column binding, e.g. '{{cat.name}}'.
+ * arguments[0] {string} The text of the repeater, e.g. 'cat in cats'.
+ * arguments[1] {number} The row index.
+ * arguments[2] {string} The column binding, e.g. '{{cat.name}}'.
+ * arguments[3] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The element in an array.
  */
 clientSideScripts.findRepeaterElement = function() {
   var matches = [];
-  var using = arguments[0] || document;
-  var repeater = arguments[1];
-  var index = arguments[2];
-  var binding = arguments[3];
+  var repeater = arguments[0];
+  var index = arguments[1];
+  var binding = arguments[2];
+  var using = arguments[3] || document;
 
   var rows = [];
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
@@ -239,17 +239,17 @@ clientSideScripts.findRepeaterElement = function() {
 /**
  * Find the elements in a column of an ng-repeat.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The text of the repeater, e.g. 'cat in cats'.
- * arguments[2] {string} The column binding, e.g. '{{cat.name}}'.
+ * arguments[0] {string} The text of the repeater, e.g. 'cat in cats'.
+ * arguments[1] {string} The column binding, e.g. '{{cat.name}}'.
+ * arguments[2] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The elements in the column.
  */
 clientSideScripts.findRepeaterColumn = function() {
   var matches = [];
-  var using = arguments[0] || document;
-  var repeater = arguments[1];
-  var binding = arguments[2];
+  var repeater = arguments[0];
+  var binding = arguments[1];
+  var using = arguments[2] || document;
 
   var rows = [];
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
@@ -323,14 +323,14 @@ clientSideScripts.findRepeaterColumn = function() {
  * Find an input elements by model name.
  * DEPRECATED - use findByModel
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The model name.
+ * arguments[0] {string} The model name.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The matching input elements.
  */
 clientSideScripts.findInputs = function() {
-  var using = arguments[0] || document;
-  var model = arguments[1];
+  var model = arguments[0];
+  var using = arguments[1] || document;
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
   for (var p = 0; p < prefixes.length; ++p) {
     var selector = 'input[' + prefixes[p] + 'model="' + model + '"]';
@@ -344,14 +344,14 @@ clientSideScripts.findInputs = function() {
 /**
  * Find elements by model name.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The model name.
+ * arguments[0] {string} The model name.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The matching elements.
  */
 clientSideScripts.findByModel = function() {
-  var using = arguments[0] || document;
-  var model = arguments[1];
+  var model = arguments[0];
+  var using = arguments[1] || document;
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
   for (var p = 0; p < prefixes.length; ++p) {
     var selector = '[' + prefixes[p] + 'model="' + model + '"]';
@@ -365,14 +365,14 @@ clientSideScripts.findByModel = function() {
 /**
  * Find buttons by textual content.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The exact text to match.
+ * arguments[0] {string} The exact text to match.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The matching elements.
  */
 clientSideScripts.findByButtonText = function() {
-  var using = arguments[0] || document;
-  var searchText = arguments[1];
+  var searchText = arguments[0];
+  var using = arguments[1] || document;
   var elements = using.querySelectorAll('button, input[type="button"], input[type="submit"]');
   var matches = [];
   for (var i = 0; i < elements.length; ++i) {
@@ -394,14 +394,14 @@ clientSideScripts.findByButtonText = function() {
 /**
  * Find buttons by textual content.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The exact text to match.
+ * arguments[0] {string} The exact text to match.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The matching elements.
  */
 clientSideScripts.findByPartialButtonText = function() {
-  var using = arguments[0] || document;
-  var searchText = arguments[1];
+  var searchText = arguments[0];
+  var using = arguments[1] || document;
   var elements = using.querySelectorAll('button, input[type="button"], input[type="submit"]');
   var matches = [];
   for (var i = 0; i < elements.length; ++i) {
@@ -421,17 +421,17 @@ clientSideScripts.findByPartialButtonText = function() {
 };
 
 
-    /**
+/**
  * Find multiple select elements by model name.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The model name.
+ * arguments[0] {string} The model name.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The matching select elements.
  */
 clientSideScripts.findSelects = function() {
-  var using = arguments[0] || document;
-  var model = arguments[1];
+  var model = arguments[0];
+  var using = arguments[1] || document;
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
   for (var p = 0; p < prefixes.length; ++p) {
     var selector = 'select[' + prefixes[p] + 'model="' + model + '"]';
@@ -445,14 +445,14 @@ clientSideScripts.findSelects = function() {
 /**
  * Find selected option elements by model name.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {string} The model name.
+ * arguments[0] {string} The model name.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} The matching select elements.
 */
 clientSideScripts.findSelectedOptions = function() {
-  var using = arguments[0] || document;
-  var model = arguments[1];
+  var model = arguments[0];
+  var using = arguments[1] || document;
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
   for (var p = 0; p < prefixes.length; ++p) {
     var selector = 'select[' + prefixes[p] + 'model="' + model + '"] option:checked';
@@ -466,14 +466,14 @@ clientSideScripts.findSelectedOptions = function() {
 /**
  * Find textarea elements by model name.
  *
- * arguments[0] {Element} The scope of the search.
- * arguments[1] {String} The model name.
+ * arguments[0] {String} The model name.
+ * arguments[1] {Element} The scope of the search.
  *
  * @return {Array.<Element>} An array of matching textarea elements.
 */
 clientSideScripts.findTextareas = function() {
-  var using = arguments[0] || document;
-  var model = arguments[1];
+  var model = arguments[0];
+  var using = arguments[1] || document;
 
   var prefixes = ['ng-', 'ng_', 'data-ng-', 'x-ng-', 'ng\\:'];
   for (var p = 0; p < prefixes.length; ++p) {

lib/locators.js

@@ -26,16 +26,15 @@ util.inherits(ProtractorBy, WebdriverBy);
  * @param {string} name
  * @param {function|string} script A script to be run in the context of
  *     the browser. This script will be passed an array of arguments
- *     that begins with the element scoping the search, and then
- *     contains any args passed into the locator. It should return
- *     an array of elements.
+ *     that contains any args passed into the locator followed by the
+ *     element scoping the search. It should return an array of elements.
  */
 ProtractorBy.prototype.addLocator = function(name, script) {
   this[name] = function(varArgs) {
     return {
       findElementsOverride: function(driver, using) {
         return driver.findElements(
-          webdriver.By.js(script), using, varArgs);
+          webdriver.By.js(script), varArgs, using);
       },
       message: 'by.' + name + '("' + varArgs + '")'
     }
@@ -52,7 +51,7 @@ ProtractorBy.prototype.binding = function(bindingDescriptor) {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
           webdriver.By.js(clientSideScripts.findBindings),
-          using, bindingDescriptor);
+          bindingDescriptor, using);
     },
     message: 'by.binding("' + bindingDescriptor + '")'
   };
@@ -68,7 +67,7 @@ ProtractorBy.prototype.select = function(model) {
   return {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
-          webdriver.By.js(clientSideScripts.findSelects), using, model);
+          webdriver.By.js(clientSideScripts.findSelects), model, using);
     },
     message: 'by.select("' + model + '")'
   };
@@ -83,7 +82,7 @@ ProtractorBy.prototype.selectedOption = function(model) {
   return {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
-          webdriver.By.js(clientSideScripts.findSelectedOptions), using, model);
+          webdriver.By.js(clientSideScripts.findSelectedOptions), model, using);
     },
     message: 'by.selectedOption("' + model + '")'
   };
@@ -99,7 +98,7 @@ ProtractorBy.prototype.input = function(model) {
   return {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
-          webdriver.By.js(clientSideScripts.findInputs), using, model);
+          webdriver.By.js(clientSideScripts.findInputs), model, using);
     },
     message: 'by.input("' + model + '")'
   };
@@ -114,7 +113,7 @@ ProtractorBy.prototype.model = function(model) {
   return {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
-          webdriver.By.js(clientSideScripts.findByModel), using, model);
+          webdriver.By.js(clientSideScripts.findByModel), model, using);
     },
     message: 'by.model("' + model + '")'
   };
@@ -129,7 +128,7 @@ ProtractorBy.prototype.buttonText = function(searchText) {
   return {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
-          webdriver.By.js(clientSideScripts.findByButtonText), using, searchText);
+          webdriver.By.js(clientSideScripts.findByButtonText), searchText, using);
     },
     message: 'by.buttonText("' + searchText + '")'
   };
@@ -144,7 +143,7 @@ ProtractorBy.prototype.partialButtonText = function(searchText) {
   return {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
-          webdriver.By.js(clientSideScripts.findByPartialButtonText), using, searchText);
+          webdriver.By.js(clientSideScripts.findByPartialButtonText), searchText, using);
     },
     message: 'by.partialButtonText("' + searchText + '")'
   };
@@ -161,7 +160,7 @@ ProtractorBy.prototype.textarea = function(model) {
   return {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
-          webdriver.By.js(clientSideScripts.findTextareas), using, model);
+          webdriver.By.js(clientSideScripts.findTextareas), model, using);
     },
     message: 'by.textarea("' + model + '")'
   };
@@ -191,23 +190,23 @@ ProtractorBy.prototype.repeater = function(repeatDescriptor) {
     findElementsOverride: function(driver, using) {
       return driver.findElements(
         webdriver.By.js(clientSideScripts.findAllRepeaterRows),
-        using, repeatDescriptor);
+        repeatDescriptor, using);
     },
     message: 'by.repeater("' + repeatDescriptor + '")',
     row: function(index) {
       return {
         findElementsOverride: function(driver, using) {
           return driver.findElements(
             webdriver.By.js(clientSideScripts.findRepeaterRows),
-            using, repeatDescriptor, index);
+            repeatDescriptor, index, using);
         },
         message: 'by.repeater(' + repeatDescriptor + '").row("' + index + '")"',
         column: function(binding) {
           return {
             findElementsOverride: function(driver, using) {
               return driver.findElements(
                   webdriver.By.js(clientSideScripts.findRepeaterElement),
-                  using, repeatDescriptor, index, binding);
+                  repeatDescriptor, index, binding, using);
             },
             message: 'by.repeater("' + repeatDescriptor + '").row("' + index +
                 '").column("' + binding + '")'
@@ -220,7 +219,7 @@ ProtractorBy.prototype.repeater = function(repeatDescriptor) {
         findElementsOverride: function(driver, using) {
           return driver.findElements(
               webdriver.By.js(clientSideScripts.findRepeaterColumn),
-              using, repeatDescriptor, binding);
+              repeatDescriptor, binding, using);
         },
         message: 'by.repeater("' + repeatDescriptor + '").column("' + binding +
             '")',
@@ -229,7 +228,7 @@ ProtractorBy.prototype.repeater = function(repeatDescriptor) {
             findElementsOverride: function(driver, using) {
               return driver.findElements(
                   webdriver.By.js(clientSideScripts.findRepeaterElement),
-                  using, repeatDescriptor, index, binding);
+                  repeatDescriptor, index, binding, using);
             },
             message: 'by.repeater("' + repeatDescriptor + '").column("' +
                 binding + '").row("' + index + '")'

spec/basic/lib_spec.js

@@ -50,8 +50,8 @@ describe('protractor library', function() {
 
   it('should allow adding custom locators', function() {
     var findMenuItem = function() {
-      var using = arguments[0]; // unused
-      var itemName = arguments[1];
+      var itemName = arguments[0];
+      var using = arguments[1]; // unused
       var menu = document.querySelectorAll('.menu li');
       for (var i = 0; i < menu.length; ++i) {
         if (menu[i].textContent == itemName) {