vapir edited this page Apr 19, 2011 · 2 revisions


This refers to the arguments that you pass to container methods such as #div, #element, #divs, or #elements.

These should be one or two arguments.1

One argument

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 :id, :value, :class, or :text. You may also use attributes which Vapir doesn’t recognize. For example, if you have an html element:

<span my_special_attribute="foo">

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: :xpath, :label, :element_object, :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.

Two arguments

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:

How What
:xpath A string containing an xpath specifying the desired element
:label ‘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 Label#for_element: ‘what’ may be a Vapir::Label element pointing at the desired element)
:element_object Generally, internal use only. ‘what’ must represent the element object, being a WIN32OLE (in IE) or a JsshObject (in Firefox)
:custom 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.
:index 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 :id, :value, :class, or :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 container.div(:unknown_attribute, 'value').


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')[1]

And :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 radio and 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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.