Add an e2e test for custom locator functions and fix doc typos.

Fixes SeleniumHQ#1531

javascript/node/selenium-webdriver/lib/webdriver.js

@@ -790,19 +790,18 @@ class WebDriver {
    *     var e1 = driver.findElement(By.id('foo'));
    *     var e2 = driver.findElement({id:'foo'});
    *
-   * You may also provide a custom locator function, which takes as input
-   * this WebDriver instance and returns a {@link WebElement}, or a
-   * promise that will resolve to a WebElement. For example, to find the first
-   * visible link on a page, you could write:
+   * You may also provide a custom locator function, which takes as input this
+   * instance and returns a {@link WebElement}, or a promise that will resolve
+   * to a WebElement. If the returned promise resolves to an array of
+   * WebElements, WebDriver will use the first element. For example, to find the
+   * first visible link on a page, you could write:
    *
    *     var link = driver.findElement(firstVisibleLink);
    *
    *     function firstVisibleLink(driver) {
    *       var links = driver.findElements(By.tagName('a'));
    *       return webdriver.promise.filter(links, function(link) {
-   *         return links.isDisplayed();
-   *       }).then(function(visibleLinks) {
-   *         return visibleLinks[0];
+   *         return link.isDisplayed();
    *       });
    *     }
    *
@@ -1659,19 +1658,18 @@ class WebElement {
    *     var e1 = element.findElement(By.id('foo'));
    *     var e2 = element.findElement({id:'foo'});
    *
-   * You may also provide a custom locator function, which takes as input
-   * this WebDriver instance and returns a {@link WebElement}, or a promise that
-   * will resolve to a WebElement. For example, to find the first visible link
-   * on a page, you could write:
+   * You may also provide a custom locator function, which takes as input this
+   * instance and returns a {@link WebElement}, or a promise that will resolve
+   * to a WebElement. If the returned promise resolves to an array of
+   * WebElements, WebDriver will use the first element. For example, to find the
+   * first visible link on a page, you could write:
    *
    *     var link = element.findElement(firstVisibleLink);
    *
    *     function firstVisibleLink(element) {
    *       var links = element.findElements(By.tagName('a'));
    *       return webdriver.promise.filter(links, function(link) {
-   *         return links.isDisplayed();
-   *       }).then(function(visibleLinks) {
-   *         return visibleLinks[0];
+   *         return link.isDisplayed();
    *       });
    *     }
    *

javascript/node/selenium-webdriver/test/element_finding_test.js

@@ -23,6 +23,7 @@ var Browser = require('..').Browser,
     By = require('..').By,
     error = require('..').error,
     until = require('..').until,
+    promise = require('../lib/promise'),
     test = require('../lib/test'),
     assert = require('../testing/assert'),
     Pages = test.Pages;
@@ -350,5 +351,42 @@ test.suite(function(env) {
             assert(el.getAttribute('value')).equalTo('two');
           });
     });
+
+    describe('by custom locator', function() {
+      test.it('handles single element result', function() {
+        driver.get(Pages.javascriptPage);
+
+        let link = driver.findElement(function(driver) {
+          let links = driver.findElements(By.tagName('a'));
+          return promise.filter(links, function(link) {
+            return link.getAttribute('id').then(id => id === 'updatediv');
+          }).then(links => links[0]);
+        });
+
+        assert(link.getText()).isEqualTo('Update a div');
+      });
+
+      test.it('uses first element if locator resolves to list', function() {
+        driver.get(Pages.javascriptPage);
+
+        let link = driver.findElement(function() {
+          return driver.findElements(By.tagName('a'));
+        });
+
+        assert(link.getText()).isEqualTo('Change the page title!');
+      });
+
+      test.it('fails if locator returns non-webelement value', function() {
+        driver.get(Pages.javascriptPage);
+
+        let link = driver.findElement(function() {
+          return driver.getTitle();
+        });
+
+        return link.then(
+            () => fail('Should have failed'),
+            (e) => assert(e).instanceOf(TypeError));
+      });
+    });
   });
 });