Skip to content
This repository has been archived by the owner on Jul 29, 2024. It is now read-only.

Commit

Permalink
docs(element): add in-code documentation for methods on element
Browse files Browse the repository at this point in the history
  • Loading branch information
juliemr committed Jan 23, 2014
1 parent cc4f7b5 commit 8348803
Showing 1 changed file with 75 additions and 1 deletion.
76 changes: 75 additions & 1 deletion lib/protractor.js
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,20 @@ var buildElementHelper = function(ptor, opt_usingChain) {
return base;
}

/**
* The element function returns an Element Finder. Element Finders do
* not actually attempt to find the element until a method is called on them,
* which means they can be set up in helper files before the page is
* available.
*
* Example:
* var nameInput = element(by.model('name'));
* browser.get('myurl');
* nameInput.sendKeys('Jane Doe');
*
* @param {webdriver.Locator} locator
* @return {ElementFinder}
*/
var element = function(locator) {
var elementFinder = {};

Expand All @@ -85,17 +99,46 @@ var buildElementHelper = function(ptor, opt_usingChain) {
return using().findElement(locator).findElement(subLocator);
};

/**
* Return the actual WebElement.
*
* @return {webdriver.WebElement}
*/
elementFinder.find = function() {
return using().findElement(locator);
};

/**
* @return {boolean} whether the element is present on the page.
*/
elementFinder.isPresent = function() {
return using().isElementPresent(locator);
};

/**
* Calls to element may be chained to find elements within a parent.
* Example:
* var name = element(by.id('container')).element(by.model('name'));
* browser.get('myurl');
* name.sendKeys('John Smith');
*
* @param {Protractor} ptor
* @param {=Array.<webdriver.Locator>} opt_usingChain
* @return {function(webdriver.Locator): ElementFinder}
*/
elementFinder.element =
buildElementHelper(ptor, usingChain.concat(locator));

/**
* Shortcut for chaining css element finders.
* Example:
* var name = element(by.id('container')).$('input.myclass');
* browser.get('myurl');
* name.sendKeys('John Smith');
*
* @param {string} cssSelector
* @return {ElementFinder}
*/
elementFinder.$ = function(cssSelector) {
return buildElementHelper(ptor, usingChain.concat(locator))(
webdriver.By.css(cssSelector));
Expand All @@ -105,24 +148,43 @@ var buildElementHelper = function(ptor, opt_usingChain) {
};

/**
* @type {function(webdriver.Locator): ElementArrayFinder}
* element.all is used for operations on an array of elements (as opposed
* to a single element).
*
* Example:
* var lis = element.all(by.css('li'));
* browser.get('myurl');
* expect(lis.count()).toEqual(4);
*
* @param {webdriver.Locator} locator
* @return {ElementArrayFinder}
*/
element.all = function(locator) {
var elementArrayFinder = {};

/**
* @return {number} the number of elements matching the locator.
*/
elementArrayFinder.count = function() {
return using().findElements(locator).then(function(arr) {
return arr.length;
});
};

/**
* @param {number} index
* @return {webdriver.WebElement} the element at the given index
*/
elementArrayFinder.get = function(index) {
var id = using().findElements(locator).then(function(arr) {
return arr[index];
});
return ptor.wrapWebElement(new webdriver.WebElement(ptor.driver, id));
};

/**
* @return {webdriver.WebElement} the first matching element
*/
elementArrayFinder.first = function() {
var id = using().findElements(locator).then(function(arr) {
if (!arr.length) {
Expand All @@ -133,17 +195,29 @@ var buildElementHelper = function(ptor, opt_usingChain) {
return ptor.wrapWebElement(new webdriver.WebElement(ptor.driver, id));
};

/**
* @return {webdriver.WebElement} the last matching element
*/
elementArrayFinder.last = function() {
var id = using().findElements(locator).then(function(arr) {
return arr[arr.length - 1];
});
return ptor.wrapWebElement(new webdriver.WebElement(ptor.driver, id));
};

/**
* @type {webdriver.promise.Promise} a promise which will resolve to
* an array of WebElements matching the locator.
*/
elementArrayFinder.then = function(fn) {
return using().findElements(locator).then(fn);
};

/**
* Calls the input function on each WebElement found by the locator.
*
* @param {function(webdriver.WebElement)}
*/
elementArrayFinder.each = function(fn) {
using().findElements(locator).then(function(arr) {
arr.forEach(function(webElem) {
Expand Down

0 comments on commit 8348803

Please sign in to comment.