Element Declarations

Element declarations are what you place in a page model to indicate what the page "looks like" in terms of the elements that exist on it and how they can be recognized, either to get information from them or to manipulate them in some way.

These aspects will be discussed on this page.

• Element Names
  • Lists
  • Tables
  • Sectional
  • Textual / Graphical / Formatting
  • Form
• Locators
  • Standard Locators
  • Element-Specific Locators
• Example Element Declarations
  • Exact or Partial Matches
  • Multiple Attribute Matches
  • CSS and XPath Locators

Element declarations are stored in page definitions. They have the following format:

elementName :friendlyName, locator

• The element name will refer to a DOM element.
• The friendly name can be preceded by a colon or you can make it a string.
• The locator will be a attribute and a value for that attribute.

As a note on the friendly name, receding by a colon is generally preferred as this makes the friendly name a Ruby symbol.

Element Names

These are what you can use for the element name portion of an element declaration. Elements can be specified in either singular or plural fashion.

• A singular element name is the same as the HTML element tag as it is recognized in the DOM or via CSS selectors.
• A plural element name is essentially the single element name, pluralized.

For example, the singular for a text field DOM element is text_field and the plural of that is text_fields. Likewise, the singular for a text area DOM element is textarea while the plural is textareas. Do note there that "text_field" has an underscore while "textarea" is a single word.

Below are the supported element names that you can use in element declarations.

Lists

ul, ol, li, dl, dt, dd

Tables

table, thead, tbody, tfoot, tr, td

Sectional

frame, iframe, div, span, article, section

Textual / Graphical / Formatting

p, link, em, strong, pre, image

Form

form, label, button, checkbox, file_field, hidden
text_field, textarea, radio, select_list, option

Locators

A locator describes how to find an element among all of the other elements on the page. This is very much like the concept of CSS selectors, which are patterns used to select an element or a set of elements.

Attributes provide additional information (meaning and context) about the element. The HTML specifications only allow certain attributes to be included on an element although it is possible for web developers to use custom attributes. Symbiont can support all of those cases.

When locating an element, the browser driver needs to be told what type of element to find and how many matches of that element to return. It's possible to return the first element, the first element that matches a certain criteria, or all matching elements. Again, Symbiont can handle all of that, and how to do it will be covered in other areas of the wiki that focus on using element declarations in test scripts.

In an element declaration, you create the locator for an element by specifying the attributes of the element and providing a value that the attribute should have.

Standard Locators

The following are standard locators that can be used on any element:

• :class
• :class_name
• :css
• :id
• :name
• :tag_name
• :xpath
• :index

Element-Specific Locators

Some elements can use specific locators based on the nature of the elements. For example, it wouldn't make sense for elements that don't have a textual component to support a text locator.

Below are some attributes and a list of the elements they can be used with:

• :text (checkbox, button, div, span, label, li, ol, ul, link, option, p, pre, select_list, strong, td, text field)
• :value (checkbox, button, hidden, option, radio, select_list, text field, textarea)
• :src (button, frame, iframe, image)
• :title (div, image, link)
• :alt (button, image)
• :for (label)
• :href (link)
• :label (text field)
• :method (form)
• :action (form)

Example Element Declarations

Consider the following page definition with element declarations, which will be used to discuss some aspects of how you can use element declarations.

class Warp
  attach Symbiont
 
  url_is 'http://localhost:9292/warp'
 
  text_field :warp_factor, id: 'warpInput'
  text_field :velocity,    id: 'velocityInput'
  text_field :distance,    id: 'distInput'
end

Exact or Partial Matches

You can look for exact or partial matches. A string object will perform an exact match. A regular expression will perform a partial match. So, for example, the :velocity element declaration could have been written like this:

text_field :velocity, id: /velo/

A partial match will return the first match found and that will be based on the positional aspect of the elements on the page. For example, you could put the following element declaration in place:

text_field :warp_field, id: /Input/

That would return the first element whose id attribute matched the pattern "Input". With the page in question, that would be the distance text field.

Multiple Attribute Matches

An element can be located using no attributes, which returns the first element. This is unlikely to be something you would want to do. An element can be located using a single property, which you can see above in the page definition. An element can also be located using multiple properties. Here's an example of what that might look like:

select_list :concepts, :class => 'required', :name => 'Concepts', title: /Choose Your/

Here a select list DOM element is provided and three specific attributes are required to make sure that the correct select list was found.

CSS and XPath Locators

A :css locator allows a css selector to be used to find an element. For more details on creating a css-selector, see the css-selector specifications. In css-locators, the square brackets are used for matching attributes.

You could replace the distInput example above with this:

text_field :distance, css: 'input#distInput'

The :xpath locator allows an element to be located based on its path. For more details on determining an element’s xpath, see the xpath specifications. Xpath is similar to css-locators, however the attribute name must be prefixed with an at symbol (@).

You could replace the distInput example above with this:

text_field :distance, xpath: '//input[@id="distInput"]'

Do note how you can refer to the text_field element type in the selector but within the css/xpath attribute value, you have to refer to input, which is the underlying DOM element type for text fields.