Join GitHub today
This refers to the arguments that you pass to container methods such as
These should be one or two arguments.1
container.div(:id => 'the_best_div')
container.tables(:class => 'ugly table')
In the one-argument form, the argument should be a Hash2. Each key of the hash should correspond to an attribute of the element, such as
:text. You may also use attributes which Vapir doesn’t recognize. For example, if you have an html element:
you can select that using:
container.span(:my_special_attribute => 'foo')
You cannot use locators which do not correspond to DOM attributes in this hash. These include:
:custom (the last two are generally only used internally, so you probably won’t ever use them at all). You must use the two-argument form with these.
In the two-argument form, the first argument should be a ‘how’ and the second argument should be a ‘what’. These are implicitly divided into two categories: Special locators that have their own behavior, and attributes on the dom which all behave in a similar manner.
There are a small number of special locators, listed here:
||A string containing an xpath specifying the desired element|
||‘what’ should be a String or Regexp matching the text of a label pointing at the desired element.
(also, for internal use only, used by
||Generally, internal use only. ‘what’ must represent the element object, being a WIN32OLE (in IE) or a JsshObject (in Firefox)|
||Internal use only. ‘what’ is a Proc which is yielded an Element and should give a true result when the yielded element matches whatever is desired.|
||An integer (or at least a string that looks like an integer) See the Index section on whether this might be deprecated.|
Any other ‘how’, such as
:text, is converted to a Hash and the rules for the one-argument form apply. One exception to the rules mentioned in the one-argument form section, however, is that if the ‘how’ is not an attribute which Vapir knows about and recognizes, then a MissingWayOfFindingObjectException will be raised – you can’t do
The fate of
:index as a specifier remains to be decided. You can currently include it in a hash of attributes (the one-argument form), like:
container.element(:class => 'my class', :index => 2) or
container.element(:index => 2) (with no other specifier)
Even though it’s not an attribute, it will be extracted and the correct index offset will be returned. A more elegant way of doing this is:
container.elements(:class => 'my class')
:index as a key of the attributes hash may be deprecated in favor of the above form.
In two-argument form, with :index its own ‘how’ specifier (that is:
container.element(:index, 3) – not in hash form) it might also be deprecated in favor of the more simple:
In any case, though, both forms will be present and supported for the immediately foreseeable future (up until vapir 2.0.0 at the very least, however far off that may be).
1 A third argument is still supported on a few elements (I think just
checkbox) for compatibility with Watir, but will be deprecated in the future and I won’t be addressing it on this page.
2 If it’s not a hash, and the element has a default ‘how’ defined, this will be used for compatibility with Watir. However, this functionality will be deprecated and I won’t be addressing that behavior on this page, either.