A Predicate is a way of referring to an element in a document, or more generally a way to indicate an action or location used to perform an action.

For TestPlan the predicates usually indicate an HTML element. This can be done via one of the many ways listed below.

General Form

The syntax of a predicate is generally type:specifier. There are additional special forms for xpath to make it is easier to specify.

Each type has a distinct specifier as documented below.

Note that not all types can be used with all types of documents or against all back-ends. We have however covered most of the common cases and built generic handlers. Should you however need something else, please let us know at https://launchpad.net/testplan↗.

Common Types

This is a listing of the more commonly used predicates. There are some additional internal or specialized ones which should generally not be used in normal circumstances.

xpath:xpath-expr

The most generic predicate is the XPath. This indicates an element in the current response according to the given xpath expression.

In place of using xpath: you can use directly any XPath expression that starts with //, ./ or @.

Note that all responses are exposed as an xml document→.

An example which selects a particular form element. The different forms are handler the same.

xpath://div[@class='entry']//form
//div[@class='entry']//form

id:id

This will match any element which has the provided id. According to the XML standard ids are to be unique, so in theory this will only ever match one given element.

name:name

This will match any element with a particular name. For HTML the name usually comes from a name attribute.

As with all predicates, if there are multiple matches, what happens depends on what is being done with the predicate. Though in many cases the first matching item will likely be used.

index:#

An index predicate can be used when there is an array of items and an index into that array makes sense.

For example, selecting the first form on a page can be done with index:0 as the Form parameter to SubmitForm→.

default

This form has no specifier and doesn't always have meaning. It indicates that if the selection has the notion of a default item then it is to be selected.

link:text

Matches any link-like element which contains the provided text. The match is a substring match, so the provided text need only appear somewhere in the complete text content of the element.

In HTML this includes at least a, but may also include buttons or other elements.

value:value

Matches an element with a value equivalent to the provided value.

In HTML this is typically the value attribute.

label:string

Matches an element based on the visible label of the element. In other words, it does a text match and finds the enclosing element -- unlike link this is not limited to link elements.

Be careful here since in the general case any matching element has any number of parent elements which also match. It is useful in places like forms where the backend knows already that it is looking for an input element with a particular label.

title:string

Does a substring match against the title of the current response.