ngpo
Create page objects with helper functions for AngularJs Protractor tests using a simple object template.
I want:
- Protractor tests as quick to write, easy to read and ignorant of the page elements as possible.
- Simple and consistent protractor page objects which can be nested.
- Consistent Protractor test methods across applicable elements and html widgets including:
- enterValue
clientPo.name.enterValue('franky');
- getValue
expect(clientPo.name.getValue()).toBe('franky');
- isVisible (true if both isPresent and isDisplayed)
expect(clientPo.name.isVisible()).toBe(true);
- No impact to existing protractor methods (unless explicitly intended)
- enterValue
- Simple and consistent way of accessing repeating and nested page elements
expect(clientPo.payments.getRow(1).amount.getValue()).toBe('423');
- Ability to easily attach custom functions to page objects.
- Ability to easily incorporate other html widgets into ngpo.
- Page Object code that's not repeated.
Install with npm install ngpo
.
ngpo v2.x: requires nodejs 6.x or greater (no breaking api changes from ngpo v1.x). Tested with angularJS v1.5.0 & 1.6.5, Protractor v5.1.2, Chrome v60.0, and chromedriver 2.31.
ngpo v1.x: Tested with Protractor versions 2.5 and 5.1.
Examples
See test\test.js and test\client.po.js for a full set of examples.
jsfiddle ngpo example.
Create a page object of Input, Dropdown & Button elements usingvar ngpo = ; var els = nameInput: locator: by po: ngpomakeInputPo name: locator: by po: ngpomakeTextPo clearNameButton: locator: byid'clear-name-button' po: ngpomakeButtonPo typeDd: locator: by po: ngpomakeDdSelectPo; var pos = ngpo;
And run a protractor test with those elements.
var clientPo = ;
jsfiddle ngpo example.
Create a list page object usingvar ngpo = ; //Nest the list elements as another 'els' object in the list object ('payments' here): var els = addPaymentButton: locator: byid'add-payment-button' po: ngpomakeButtonPo payments: locator: by po: ngpomakeListPo els: amountInput: locator: by po: ngpomakeInputPo amount: locator: by po: ngpomakeTextPo ; var pos = ngpo;
Run the protractor test.
var clientPo = ; ;
Documentation
ngpo Functions available:
makePos
- Make page object functions and the functions attached (in addition to all expected Protractoor functions):
makeDefaultPo
makeTextPo
makeInputPo
makeDateInputPo
- enterValue
- getValue
- getValueTrim
- isVisible
- getValueMmddyyyy
- getValueYyyymmdd
makeButtonPo
makeButtonWithPausePo
(deprecated)makeDdSelectPo
- enterValue
- getValue
- getValueTrim
- isVisible
- clear (selects first item in dd list)
makeParentPo
- getValue
- subPo.poFn()
makeListPo
- getRow
- getRow(n).subPo.poFn()
- getCount
- getValue
- poFns (optional fns that can be attached to page objects; see Append custom functions to page object elements)
hasClass
,makeHasClassFn
:expect(clientPo.deleteHobbyButton.hasClass('yada')).toBe(true)
clearByBs
,makeHasClearByBs
(use to clear date field in Chrome; Protractor issue #562) :clientPo.dobInput.clearByBs()
clickWithPause
(deprecated)getAttributeValue
- Other functions
- pause
- acceptAlert
- dismissAlert
How to
- Append custom functions to page object elements
- Clear a date field in Chrome (Protractor Issue #562) - Use
poFns.clearByBs
. See example in Append custom functions to page object elements. - Nest ngpo page objects.
- Create your own makePo functions: See
makeDefaultPo
. And github/npm it: See ngpo-ui-select.
ngpo functions attached to page objects
enterValue()
Enters a value into a page element and returns a Promise. How value is entered depends on the page element. Input elements use:
return el clear ;
Example:
clientPonameInput;;
getValue()
Returns the value of the pageObject as a Promise. How value is retrieved depends on the page element:
- makeTextPo() uses Protractor getText()
- input POs (makeInputPo, makeDateInputPo) use Protractor
getAttribute('value')
- makeDdSelectPo uses el.$('option:checked').getText()
clientPonameInput;; // input; // text by.binding
getValueTrim()
Returns pageObject.getValue() to a string.trim() as a Promise.
clientPonameInput; ;
isVisible()
Returns true as a Promise if isPresent and isDisplayed.
;;;// hide showme elementclientPoshowmeButton;
ngpo api functions
makePos(els)
Returns a Page Object: An object-literal of Protractor ElementFinder objects possibly with methods appended. Methods appended are based on the els object passed in.
makePos
calls the function assigned to the po
property for every object in the els
object. The po
function is called with (1) the locator
and (2) the respective els object.
els
is an object of the form :
var els poName1: locator: protractorLocator // Req'd. eg; by.model('client.city') po: makePoFn //Req'd. the function to append helper functions and return a protractor ElementFinder els: ... // optional nested object of same form els for list or parent pos fns:
Example
var ngpo = ; var els = nameInput: locator: by po: ngpomakeInputPo myOption: 'abc'; var pos = ngpo;
In the above example, when makePos
is called, makeInputPo
will be called with
And return an object with the property nameInput
which would be a protractor ElementFinder with getValue and enterValue methods appended (from makeInputPo).
makeDefaultPo(elOrLoc, options)
Returns a Protractor ElementFinder with only the isVisible
ngpo function appended.
Determines if elOrLoc
is a Protractor ElementFinder or locator. If it is a locator, creates an ElementFinder from it and returns that ElementFinder. Otherwise, returns ElementFinder as-is. options
is the els object for the page object being created; eg, {locator: by.binding('client.name'), po: ngpo.makeTextPo}
.
Every makeXxxPo function calls this function first. Custom makeXxxPo functions should also call this function first as well which will ensure that it will work as a 'sub' PO in list and parent elements.
Example
{ var el = ; var yank = options && optionsyank ? optionsyank : ''; el = { return el === yank; } return el; } var els = berl: locator: by po: myCustomPo yank: 'green'
makeTextPo(elOrLoc, options)
Returns a Protractor ElementFinder with one appended function:
- getValue - returns element.getText()
Arguments: See makeDefaultPo
and makePos
.
Would typically be used with by.binding.
var ngpo = ; var els = name: locator: by po: ngpomakeTextPo; var pos = ngpo;
makeInputPo(elOrLoc, options)
Returns a Protractor ElementFinder for html <input>
with these appended functions:
- getValue - returns element.getText()
- enterValue(value) : returns
element.click().clear().sendKeys(value).sendKeys(protractor.Key.TAB)
Arguments: See makeDefaultPo
and makePos
.
Example
var ngpo = ; var els = nameInput: locator: by po: ngpomakeInputPo; var clientPo = ngpo; // test example clientPonameInput; ;
makeDateInputPo(elOrLoc, options)
Returns a Protractor ElementFinder for html <input type=date>
tags with these appended functions:
- getValue - See
makeInputPo
- enterValue(value) - See
makeInputPo
- getValueMmddyyyy - getValue() as string mm/dd/yyyy format
- getValueYyyymmdd - getValue() as string yyyy-mm-dd format
Arguments: See makeDefaultPo
and makePos
.
Example
var ngpo = ; var els = dobInput: locator: by po: ngpomakeDateInputPo; var clientPo = ngpo; // test example clientPodobInput; ; ;
makeButtonPo(elOrLoc, options)
Returns a Protractor ElementFinder with no appended functions.
Arguments: See makeDefaultPo
and makePos
.
Example
var ngpo = ; var els = deleteCityButton: locator: byid'delete-city-button' po: ngpomakeButtonPo; var clientPo = ngpo; // test example clientPodeleteCityButton;
makeButtonWithPausePo(elOrLoc, options)
Returns a Protractor ElementFinder with this amended function.
click()
: sleeps foroptions.pause
milleseconds after click()element.click().then(function() {pause(options.pause);});
Arguments: See makeDefaultPo
and makePos
.
Original ElementFinder click() method is available via element.p.click().
Example
var ngpo = ; var els = deleteHobbyButton: locator: byid'delete-hobby-button' po: ngpomakeButtonWithPausePo pause: 5000; var clientPo = ngpo; // test example clientPodeleteHobbyButton; // pauses 5 seconds after click()
makeDdSelectPo(elOrLoc, options)
Returns a Protractor ElementFinder for html <select>
tags
with these appended functions :
- getValue - returns
element.$('option:checked').getText()
- enterValue(value) : returns
element.click().sendKeys(value).sendKeys(protractor.Key.TAB)
Arguments: See makeDefaultPo
and makePos
.
Example
var ngpo = ; var els = nameInput: locator: by po: ngpomakeInputPo; var clientPo = ngpo; // test example clientPonameInput; ;
makeParentPo(elOrLoc, options)
Returns a Protractor ElementFinder which can have sub-ElementFinders on it.
Arguments: See makeDefaultPo
and makePos
.
Example
var ngpo = ; var els = request: locator: byid'request' po: ngpomakeParentPo els: rInput: locator: by po: ngpomakeInputPo rText: locator: by po: ngpomakeTextPo ; var clientPo = ngpo; // test example clientPorequestrInput; ; ;
makeListPo(elOrLoc, options)
Returns a Protractor element.all object with nested protractor ElementFinders. It has these appended functions:
- getRow(n)
- getRow(n).subPo.poFn()
- getCount
- getValue
Arguments: See makeDefaultPo
and makePos
.
Example
var ngpo = ; var els = payments: locator: by po: ngpomakeListPo els: amountInput: locator: by po: ngpomakeInputPo amount: locator: by po: ngpomakeTextPo ; var clientPo = ngpo; // test example ; clientPopaymentsamountInput; ; ;
How to Nest Page Objects
Example to nest the transportation page object into a client page object.
// transportation.po.jsvar ngpo = ; var els = transportationInput: locator: by po: ngpomakeInputPo transportation: locator: by po: ngpomakeTextPo ; var pos = ngpo; moduleexports = pos;
There are 2 ways to nest the above transportation page object.
// client.po.jsvar ngpo = ; var transPo = ; // (1) directly in the client po els objectvar els = transportationParent: locator: byid'trans-parent' po: ngpomakeParentPo els: transPoels ; // (2) append the transportation page objects elements directly to the client po object var pos = ngpo; pos = ngpo;
The protractor tests would refer to these like this:
// #1 above would be called using transportationParent: clientPotransportationParenttransportationInput; ; // #2 would allow the transportation page object elements to be called directly from the client po clientPotransportationInput; ;
How to append custom functions to page object elements
Custom functions can be included in the els fns
property object. Custom functions are called with the ElementFinder and the options object (see makeDefaultPo), so that you can refer to them in the custom function, and the arguments that you call the function with from the protractor script.
Example
var els = hobbyInput: locator: by po: ngpomakeInputPo pause: 5000 fns: {return el;} { return el } funnyInput: locator: by po: ngpomakeInputPo fns: { var addedVals = val1 + val2; return funnyInputEl; } dobInput: locator: by po: ngpomakeDateInputPo // override clear() fn with poFns.clearByBs b/c Protractor Issue #562 fns: clear: ngpopoFnsclearByBs; // test example ; clientPohobbyInput; // pauses 5 seconds after click() clientPofunnyInput ; clientPodobInput ;