(function () {
"use strict";
// polyfill
if ( !Array.prototype.forEach ) {
Array.prototype.forEach = function(fn, scope) {
for(var i = 0, len = this.length; i < len; ++i) {
fn.call(scope, this[i], i, this);
}
}
}
/**
* Add properties from source object to target object
*/
function _extend (target, source) {
for (var prop in source) {
target[prop] = source[prop];
}
}
/**
* Provides several functions that make using WebDriver more
* convenient.
*
* @example
* var webdriver = require('selenium-webdriver'),
* WebDriverHelpers = require('webdriver-helpers'),
* driver,
* helpers;
*
* driver = require('./drivers/selenium-server.js')(webdriver, {
* browserName: 'chrome',
* seleniumProtocol: 'WebDriver',
* 'chrome.switches': ['--window-size=1366,768'] // this is being ignored
* });
*
* driver.manage().timeouts().setScriptTimeout(5000);
* driver.manage().timeouts().implicitlyWait(5000);
*
* helpers = new WebDriverHelpers(webdriver, driver);
*
* function login (email, password) {
* helpers.populateElements({
* '#login-email': email,
* '#login-password': password
* });
*
* helpers.id('login-submit-btn').click();
* }
*
* @class WebDriverHelpers
* @param {Object} webdriver selenium-webdriver instance
* @param {Object} driver browser driver instance
* @return {Object} object with several convenience functions
* @constructor
*/
var WebDriverHelpers = function (webdriver, driver) {
this.flow = webdriver.promise.controlFlow();
this.webdriver = webdriver;
this.driver = driver;
};
_extend(WebDriverHelpers.prototype, {
/**
* Sugar for: this.driver.findElement(this.webdriver.By.name(args))
*
* @method name
* @param {String} args
* @return {Object} webdriver element
*/
name: function (args) {
return this.driver.findElement(this.webdriver.By.name(args));
},
/**
* Sugar for: this.driver.findElement(this.webdriver.By.id(args))
*
* @example
* helpers.id('btnSubmit').click()
* @method id
* @param {String} args
* @return {Object} webdriver element
*/
id: function (args) {
return this.driver.findElement(this.webdriver.By.id(args));
},
/**
* Sugar for: this.driver.findElement(this.webdriver.By.tagName(args)
*
* @example
* var verifyOnCheckinPage = function () {
* helpers.tagName('h1').then(function (h1) {
* h1.getText().then(function (text) {
* expect(text).toBe("Check-In");
* });
* });
* };
* @method tagName
* @param {String} args
* @return {Object} webdriver element
*/
tagName: function (args) {
return this.driver.findElement(this.webdriver.By.tagName(args));
},
/**
* Sugar for: this.driver.findElement(this.webdriver.By.className(args))
*
* @method className
* @param {String} args
* @return {Object} webdriver element
*/
className: function (args) {
return this.driver.findElement(this.webdriver.By.className(args));
},
/**
* Selects a drop-down option by value
*
* @method selectByValue
* @param {webdriver.Locator|Object.<string>} locator The locator
* strategy to use when searching for the select element.
* @param {string} value The value of the option to select
*/
selectByValue: function (locator, value) {
var selElement = this.driver.findElement(locator);
selElement.findElement(this.webdriver.By.css("option[value='" + value + "']"))
.click();
},
/**
* Selects a radio button element by value
*
* @method radioByValue
* @param {string} name The name of the radio button group
* @param {string} value The value of the option to select
*/
radioByValue: function (name, value) {
var locator = "input[name='" + name + "'][value='" + value + "']";
this.driver.findElement(this.webdriver.By.css(locator))
.click();
},
/**
* Pauses for a short amount of time, giving webdriver time
* to re-render the page, if needed.
*
* @example
* var authenticate = function () {
* var name = 'Teacher User',
* email = 'teacher@example.com',
* password = 'password',
* deferred = webdriver.promise.defer(),
* i = 0;
*
* helpers.populateElements({
* '#login-email': email,
* '#login-password': password
* });
* helpers.id('login-buttons-password').click();
* helpers.avoidStaleElement();
* helpers.id('display-name-link').getText()
* .then(function (text) {
* var expected = name;
* if (text.indexOf(expected) !== 0) {
* deferred.reject(new Error(text + ' did not contain ' + expected));
* } else {
* deferred.resolve();
* }
* });
*
* return deferred.promise;
* };
*
* @method avoidStaleElement
*/
avoidStaleElement: function () {
var i = 0;
this.driver.wait(function () {
i++;
//console.log(i);
return (i > 3);
}, 3000);
},
/**
* Easily set values of form elements by passing a map of
* css selector / element value pairs.
*
* @example
* // populate a radio button group, a select box, a text
* // input and a textarea
* var helpers = new WebDriverHelpers(webdriver, driver);
* helpers.populateElements({
* 'input[name="gender"][value="M"]': 'M',
* '#country': "United States",
* '#age': '34',
* '#comment': "example msg"
* });
*
* @method populateElements
* @param {Object} locatorValuePairs key/value pairs consisting of a css
* string locator for a form element and a string or
* array of strings to populate the element with.
*/
populateElements: function (locatorValuePairs) {
var key,
value,
locator,
singleWord;
for (key in locatorValuePairs) {
value = locatorValuePairs[key];
locator = { css: key };
// optimize 'id' case
singleWord = -1 === key.indexOf(' ');
if (singleWord &&
'#' === key.charAt(0)) {
locator = { id: key.substring(1) };
}
//console.log("locator ", locator, ", value ", value);
this.populateElement(locator, value);
}
}, // end populateElements
/**
* Find first element in a group who's text matches parameter.
*
* @example
* var findPersonByName = function (nameOfPerson) {
* var collectionLocator = {
* 'css':'div.people > .person'
* },
* criteriaLocator = {
* 'className':'name'
* };
*
* return findElementInCollectionByText(
* collectionLocator,
* criteriaLocator,
* nameOfPerson
* );
* };
*
* //...can be called like:
*
* it("can click person",
* function (done) {
* authenticate().
* then(findPersonByName("Jeff Winger")).
* then(clickPerson).
* then(finish(done), error);
* });
*
* //...and will match:
*
* <div class="people">
* <div class="person">
* <p class="name">Jeff Winger</p>
* <p class="pic">...</p>
* </div>
* </div>
*
* @method findElementInCollectionByText
* @param {webdriver.Locator|Object.<string>} collectionLocator The locator
* for the group of elements to search
* @param {webdriver.Locator|Object.<string>} criteriaLocator The locator
* for the element who's text should be compared, relative to collection
* @param {string} text The text to search for.
* @return {function} A function that, when executed, returns a promise that
* will be resolved with the matching element.
*/
findElementInCollectionByText: function (collectionLocator, criteriaLocator, text) {
var self = this;
return function () {
var mainDefer = self.webdriver.promise.defer();
self.driver.findElements(collectionLocator).
then (function (collection) {
var matchDefer = self.webdriver.promise.defer(),
matchPromise = matchDefer.promise,
resolved;
//console.log('found elements');
collection.map(function (item) {
item.findElement(criteriaLocator).
then (function (elem) {
self.flow.execute(function () {
elem.getText().
then (function (value) {
//console.log('comparing ' + value);
if (value === text) {
resolved = true;
matchDefer.resolve(item);
}
});
});
});
});
self.flow.execute(function () {
matchPromise.then(function (item) {
//console.log('mainDefer.resolve');
mainDefer.resolve(item);
});
//console.log('resolved? ' + resolved);
if (!resolved) {
throw new Error('failed to find target element ' +
JSON.stringify(collectionLocator) +
JSON.stringify(criteriaLocator) +
text);
}
});
}); // end findElements.then
return mainDefer.promise;
};
}, // end findElementInCollectionByText
/**
* Populate textbox(es) with string value(s). If 'strings' is an
* array, locator is assumed to match a group of textboxes which
* all have the same name.
*
* This function performs a new find for each subsequent textbox
* in order to support dynamically added inputs. For example, when
* a second input field is added once a value is entered into the
* first input.
*
* @example
* var populateFriends = function (names) {
* var locator = {className: "friends-mlText"};
* return helpers.populateTextBox (locator, names);
* };
*
* @method populateTextBox
* @param {webdriver.Locator|Object.<string>} locator The locator
* strategy to use when locating the target input box(es)
* @param {string | array<string>} strings The values to populate
* into the text box(es)
* @return {function} A function which, when executed, populates
* the target text boxes
*/
populateTextBox: function (locator, strings) {
var self = this;
if ('string' === typeof strings) {
return function () {
self.driver.findElement(locator).sendKeys(strings);
}
}
if ('number' !== typeof strings.length) {
throw new Error("invalid type for parameter 'strings'");
}
// else, assume strings is an Array
return function () {
var stringCount = strings.length,
i,
populateTextBoxByIndex;
// populate first string
self.driver.findElement(locator).sendKeys(strings[0]);
populateTextBoxByIndex = function (i) {
// use closure to save appropriate index
self.driver.findElements(locator).
then (function (collection) {
// sanity check
if (i >= collection.length) {
throw new Error("failed to locate text box for target string '" +
strings[i] + "'.");
}
collection[i].sendKeys(strings[i]);
});
};
// populate the rest of the names
for (i = 1; i < stringCount; i++) {
populateTextBoxByIndex(i);
}
}
}, // end populateTextBox
/**
* Sets the value of a form element.
*
* Supports the following form elements:
* input - text, radio, email, password
* textarea
* select
*
* @method populateElement
* @param {webdriver.Locator|Object.<string>} locator The locator
* strategy to use when searching for the form element.
* @param {string | array<string>} strings The target value(s) of
* into the form element(s)
*/
populateElement: function (locator, value) {
var self = this;
if ('string' !== typeof value) {
// assume a group of dynamically-added text boxes
// aka. Multi-List
this.populateTextBox(locator, value)();
return;
}
// assume regular, non-dynamic, form element
this.driver.findElements(locator).then(function (collection) {
collection.forEach(function (elemPromise) {
elemPromise.then(function (element) {
element.getTagName().
then(function (tagName) {
switch (tagName) {
case "select":
element.findElement(self.webdriver.By.css("option[value='" + value + "']"))
.click();
break;
case "textarea":
element.sendKeys(value);
break;
case "input":
element.getAttribute("type").
then(function (type) {
switch (type) {
case "radio":
// click if value matches
element.getAttribute("value").
then(function (val) {
if (val === value) {
element.click();
}
});
break;
case "text":
case "email":
case "password":
element.sendKeys(value);
break;
default:
throw new Error ("Unsupported input type '" + type + "'");
}
});
break;
default:
throw new Error ("Unsupported form element '" + tagName + "'");
}
})
})
})
});
} // end populateElement
}); // end _extend WebDriverHelpers.prototype
module.exports = WebDriverHelpers;
})();
