AMOlocators

From MozillaWiki
Jump to: navigation, search

NOTE: The AMOlocators module is currently in transition to another structure which uses nested classes as described in the next section. It will be expanded to support new scripts and updates to existing scripts.

The earlier structure used dictionaries named for a page or a list and keyed by mnemonics for the element. There is no plan to continue expanding it, but it will remain in the module until no scripts reference the dictionaries. The dictionaries are described starting in the section "Naming convention for dictionaries".

Locators arranged in nested classes

The locators are defined as simple string 'constants' in nested classes to allow a script writer to take advantage of autocomplete features in IDEs by "building a path" to a locator. The highest level classes are pages around a major features such as Personas or Collections. Within them are classes for types of pages, such as landing or browse pages. These classes will have locators for elements or nodes, and subclasses for groups of elements which themselves contain additional locators.

Class names, representing a page or a section which contains elements, are capitalized. Locator names are all lowercase. An IDE's autocomplete feature often differentiates between classes and variables with different icons.  An example of using autocomplete in an IDE that's aware of classes:

  1. While editing a script after typing "AMOlocators." (or an instance) a list classes appears containing Categories, Collections, Personas.
  2. After selecting a class and entering '.' another list appears for the classes within it, perhaps BrowsePage, LandingPage, SearchResults.
  3. After selecting one of these classes (pages) a longer list appears with variables and classes.  This is where a locator for the page's header <h2> tag or breadcrumb will appear if it's defined.  The list may contain a locator for an entire info box and/or locators for individual elements such as the info box's header, description and link.  An element containing many sub-elements will likely have a class that defines locators for the sub-elements.

Locators that can reference an n-th item in a list are embedded with "%s" at the item index. They are intended to be as string formators which are combined with an index variable to create a complete locator. For more information see the discussion about locators containing the word "Indexed".

Locators that can reference an option within a list of options (such as sort options) may also use a "%s" as a placeholder for the specific option value. They are intended to be a string formator which are combined with a value to create a complete locator. For more information see the discussion about locators containing the word "Keyed"

About missing locators:If a script would benefit from pages and/or elements not in AMOlocators, talk to Truman about updating the module.

Naming conventions

Locator variable names that contain an HTML tag type generally have a locator string that ends with that tag type. For example, detailLink, sortSelect refer to a link <a> and a select control respectively.

When elements are nested, a section of text could be addressed by more than one locator.  Generally the prefered locator is the one with a descriptive attrribute, such as ...class='name'.  When nest elements are equally non-descriptive the higher element is generally used for the locator.

Multiple variables may use same locator to capture difference usages of the element. This allows variable names that reflect the usage of the locator, and perhaps simplify script updates when an element that served two purposes becomes two elements.

NOTE: the examples are illustrative of class and variable names. Some example might not yet exist in the module.

Special words in locator names

item

  • Locator constants named 'item' refer to an entire item (i.e. an add-on) within a list of items. Since they don't contain an n-th item index they will point to the first item in the or are suitable for get_xpath_count( )
  • Suitable for: get_xpath_count( )
  • Example: itemCount = sel.get_xpath_count ( AMOlocators.AddonCategories.BrowsePage.AddonList.item )
  • Could use with is_element_present( ) to check if a list contains any items.
  • Class names containing 'Item' are a group of locators for elements within an item, such as AMOlocators.AddonCategories.BrowsePage.AddonList.ItemIndexed.name. Generally the locators will include an index. see Locators that require a parameter below.


*Indexed

  • Used to index into a list of items. see Locators that require a parameter below.

*Keyed

  • Used for a single locator that references into a set of similar elements that differ by a segment. see Locators that require a parameter below

*Link

  • Locator for a link. Locator string ends with an <a> tag.
  • Suitable for sel.click( )
  • Example: sel.click( AMOlocator.AddonCategories.BrowsePage.AddonList.detailLink % idx ) clicks on the detail page link for the idx-th add-on listed in the browse page.
  • Suitable for sel.get_attribute for href or other attribute in the <a> node.
  • Example: sel.get_attribute( AMOlocator.AddonCategories.LandingPage.TopRatedList.viewAllLink + "@href" ) retrieves the href attribute from the View All link of the Top Rated list on the category landing page.

*Select

  • Locator for a select control. The last element in the locator is a <select>.
  • Suitable for sel.select( )
  • Example: sel.select( AMO_locators.addonCategories.BrowsePage.sortSelect, 'value=' + sortOption) selects the sort option with the 'value' attribute specified by sortOption, found on the add-ons browse page.

*Option

  • Locator to an option in a select control. The last node in the locator is an <option>.

*Selected*

  • Locator includes qualifiers to find the item that is selected in a list, typically by including @class='selected'. They are are defined for lists of 'li' or 'div' tags where the selenium get_selected_* calls can't be used.


Locators that require a parameter

Some locator strings require a parameter to complete them. They contain '%s' to format/insert into a value into the locator. In some cases the parameter is an index into a list. In other cases it is a variation within a set of similar locators.

Locators that require an index - example:

addonName = get_text( AMOlocators.addonCategories.BrowsePage.AddonList.ItemIndexed.name % addonIdx )

retrieves the text for the name for the item # specified by AddonIdx. The list is on the add-on browse page.


Locators that require a key value- example

sel.click ( AMOlocators.Addons.HomePage.List.sortLinkKeyed % sortOpt )

clicks on the link containing the value in sortOpt.  A locator string containg "a[contains(@href, '?featured=%s)]" will create locators containing "a[contains(@href,'?featured=popular')] "and "a[contains(@href,'?featured=updated')]" when sortOpt is 'popular' or 'updated', respectively.


Confirming the element that a locator references

Selenium IDE has a feature that takes a locator and highlights the related element on the web page.

1. Open Selenium IDE.

2. Highlight a command containing the locator of interest as the command's first parameter, or select an empty command and enter the locator in the Target field.

  • The locator may be XPath or CSS.
  • It must be a literal without any beginning or ending quotes.
  • Any formatting, i.e. [%s], must be removed or replaced to create a valid locator.

3. Position the Se IDE and the browser displaying the web page on the screen so that the Se IDE window and the intended element on the web page are both visible at the same time.

4. In Se IDE select the Find button, next to the Target input containing the locator.

The result is either a) the element on the web page referenced by the locator is highlighted in green, or b) an error is displayed in Se IDE if the element is not found or the XPath is invalid.


Naming convention for dictionaries

NOTE: Store locator names in dictionaries will be removed from this module in the future

..._List[ ] references elements that appear once on a list, such as headers or sort selectors.

..._List_Item[ ] references elements on a particular item in a list. All keys require an index value into the list. see Locators that require a parameter below.

Example:

  • addonCategoryLandingPage_RecentList['title'] is a locator to the title of the Recent list on the add-on category landing page
  • addonCategoryLandingPage_RecentList_Item['name'] % 3 creates a locator for the name of the 3rd add-on in the same list


Naming conventions for dictionary keys

Locators for controls that have an action will include the tag type at the end of the key. For example: detailLink, sortSelect. Keys for static elements may include the tag type to reference a specific element, such as PreviewImg.

Dictionary keys that don't end with a tag type generally refer to a section of text or a higher level node.

item

  • Dictionaries that reference a list use this key for an entire item (i.e. add-on).
  • ..._List['item'] refers to the item node on the list without an index. 
  • Suitable for: get_xpath_count( )
  • Example: itemCount = sel.get_xpath_count ( AMOlocators.addonBrowsePage_List['item'] )
  • Could use with is_element_present to check if a list contains any items.
  • ..._List_Item['item'] refers to the item node with an index.  To access a particular element on the n-th item, the mnemonic key for that element is generally used rather than appending to this locator.

name

  • Locator to a node with the item name.
  • Suitable for sel.get_text( )
  • Example: addonName = get_text( addonBrowsePage_List_Item[name] % idx ) retrieves the text for the name on the idx-th add-on in the list on the browse page.

*Link

  • Locator for a link. The last element in the locator is an <a>.  Key name may simply be link for an item with only a few elements, or may be prefixed with the link destination or the element containing the link.
  • Suitable for sel.click( )
  • Example: sel.click( AMOlocator.addonBrowsePage_List_Item['detailLink'] % idx ) clicks on the detail page link for the idx-th add-on listed in the browse page.
  • Suitable for sel.get_attribute for href or other attribute in the <a> node.
  • Example 2: sel.get_attribute( AMOlocator.addonCategoryLandingPage_TopRatedList['ViewAllLink'] + "@href" ) retrieves the href attribute from the View All link of the Top Rated list on the category landing page.

*Select

  • Locator for a select control. The last node in the locator is a <select>.
  • Suitable for sel.select( )
  • Example: sel.select( AMO_locators.addonsSearchResults['sortSelect'], 'value=' + sortOption) selects from the add-ons search results page the sort option with the 'value' attribute specified by sortOption.

*Option

  • Locator to an option in a select control. The last node in the locator is an <option>.

starsRating

  • Locator to the node containing the rating (i.e. "4 out of 5 stars") elements.

*Indexed

  • Locator requires a parameter in order to index into a list. see Locators that require a parameter below.

*Keyed

  • Locator requires a parameter to specify a locator with a set of similar locators. see Locators that require a parameter below.

and many more


Locators that require a parameter

Some locators require a parameter to complete them. They contain '%s' and must be followed by " % value", where value is a literal or variable. Sometimes the parameter is an index into a list. In other cases it is a variation within a set of similar locators.

Locators that require an index

  • Example: addonName = get_text( AMOlocators.addonBrowsePage_List_Item[name] % AddonIdx ) # retrieves the text for the name for the item # specified by AddonIdx. The list is on the add-on browse page.
  • all locators in the ..._List_Item[ ] dictionaries require an index.
  • dictionary keys that end in Indexed require an index.

Locators that require a key value

  • Example: sel.click ( AMOlocators.addonHomePage_List['sortLinkKeyed'] % sortOption ) clicks on a link that contains a[contains(@href,'?featured=popular')] or a[contains(@href,'?featured=updated')], and sortOption contains the value string 'popular' or 'updated', respectively.
  • dictionay keys that end in 'Keyed' require a key value