Element locators

Shadow DOM also supported

Since v4.8.0, you can use the @ShadowRoot annotation on any locator step to refer to a shadow root element. Example

<element> can be located by <selector> "<expression>"

Binds a selector for a web element to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation.

Where

<element> is the web element name
<selector> is the selector type, one of:
- id for selecting by id attribute
- name for selecting by name attribute
- tag name (or tag since v2.46.0) for selecting by tag name
- css selector (or css since v2.46.0) for selecting by css expression
- class name (or class since v2.46.0) for selecting by class attribute
- xpath for selecting by XPath
- link text for selecting by link text
- partial link text for selecting by partial link text
- javascript (or js since v2.46.0) for selecting by JavaScript
<expression> is the selector expression

Example

  Given the todo field can be located by class "new-todo"
   When I enter "Walk the dog" in the todo field

With explicit timeout since v3.73.0

  Given @Timeout('10s') the todo field can be located by class "new-todo"
   When I enter "Walk the dog" in the todo field

Without any timeout since v3.73.0

  Given @Timeout('0s') the todo field can be located by class "new-todo"
   When I enter "Walk the dog" in the todo field

Link

Learn more

Since v1.0.0

<element> can be located by <selector> "<expression>" at index <index>

Binds an indexed selector for a web element to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation.

Where

<element> is the web element name
<selector> is the selector type, one of:
- id for selecting by id attribute
- name for selecting by name attribute
- tag name (or tag since v2.46.0) for selecting by tag name
- css selector (or css since v2.46.0) for selecting by css expression
- class name (or class since v2.46.0) for selecting by class attribute
- xpath for selecting by XPath
- link text for selecting by link text
- partial link text for selecting by partial link text
- javascript (or js since v2.46.0) for selecting by JavaScript
<expression> is the selector expression
<index> is the index of the element to select in list returned by <expression>

Example

  Given the first item can be located by css ".todo-list label" at index 0
   Then the first item should contain "Walk the dog"

With explicit timeout since v3.73.0

  Given @Timeout('12s') the first item can be located by css ".todo-list label" at index 0
   Then the first item should contain "Walk the dog"

Without any timeout since v3.73.0

  Given @Timeout('0s') the first item can be located by css ".todo-list label" at index 0
   Then the first item should contain "Walk the dog"

Link

Learn more

Since v2.28.0

<element> can be located by <selector> "<expression>" at index <index> in <otherElement>

Binds an indexed selector for a web element (contained in another) to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation.

Where

<element> is the web element name
<selector> is the selector type, one of:
- id for selecting by id attribute
- name for selecting by name attribute
- tag name (or tag since v2.46.0) for selecting by tag name
- css selector (or css since v2.46.0) for selecting by css expression
- class name (or class since v2.46.0) for selecting by class attribute
- xpath for selecting by XPath
- link text for selecting by link text
- partial link text for selecting by partial link text
- javascript (or js since v2.46.0) for selecting by JavaScript
<expression> is the selector expression
<index> is the index of the element to select in list returned by <expression>
<otherElement> is the name of the web element that this one is relative to

Example

  Given the count info can be located by class "todo-count"
    And the count unit can be located by tag "span" at index 1 in the count info
   Then the count unit should contain "item"

With explicit timeout since v3.73.0

  Given @Timeout('20s') the count info can be located by class "todo-count"
    And @Timeout('10s') the count unit can be located by tag "span" at index 1 in the count info
   Then the count unit should contain "item"

Without any timeout since v3.73.0

  Given @Timeout('0s') the count info can be located by class "todo-count"
    And @Timeout('0s') the count unit can be located by tag "span" at index 1 in the count info
   Then the count unit should contain "item"

Link

Learn more

Since v2.28.0

<element> can be located by
selector     | expression     |
<selector 1> | <expression 1> |
<selector 2> | <expression 2> |
    ..      |       ..       |
<selector n> | <expression n> |

Binds primary and fallback selectors for a web element to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation. Lookups will be attempted in the order specified until one succeeds.

Where

<element> is the web element name
<selector n> is the nth selector type, one of:
- id for selecting by id attribute
- name for selecting by name attribute
- tag name (or tag since v2.46.0) for selecting by tag name
- css selector (or css since v2.46.0) for selecting by css expression
- class name (or class since v2.46.0) for selecting by class attribute
- xpath for selecting by XPath
- link text for selecting by link text
- partial link text for selecting by partial link text
- javascript (or js since v2.46.0) for selecting by JavaScript
<expression n> is the nth selector expression

Example

  Given the todo field can be located by
selector | expression  |
name     | todo-field  |
css      | .todo input |
class    | new-todo    |
   When I type "Feed the cat" in the todo field

With explicit timeout since v3.73.0

  Given @Timeout('8s') the todo field can be located by
selector | expression  |
name     | todo-field  |
css      | .todo input |
class    | new-todo    |
   When I type "Feed the cat" in the todo field

Without any timeout since v3.73.0

  Given @Timeout('0s') the todo field can be located by
selector | expression  |
name     | todo-field  |
css      | .todo input |
class    | new-todo    |
   When I type "Feed the cat" in the todo field

Link

Learn more

Since v2.11.0

<element> can be located at index <index> by
selector     | expression     |
<selector 1> | <expression 1> |
<selector 2> | <expression 2> |
    ..      |       ..       |
<selector n> | <expression n> |

Binds indexed primary and fallback selectors for a web element to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation. Lookups will be attempted in the order specified until one succeeds.

Where

<element> is the web element name
<selector n> is the nth selector type, one of:
- id for selecting by id attribute
- name for selecting by name attribute
- tag name (or tag since v2.46.0) for selecting by tag name
- css selector (or css since v2.46.0) for selecting by css expression
- class name (or class since v2.46.0) for selecting by class attribute
- xpath for selecting by XPath
- link text for selecting by link text
- partial link text for selecting by partial link text
- javascript (or js since v2.46.0) for selecting by JavaScript
<expression n> is the nth selector expression
<index> is the index of the element to select in list returned by <expression n>

Example

  Given the second item can be located at index 1 by
selector | expression       |
name     | todo-label       |
class    | todo-label       |
css      | .todo-list label |
   Then the second item should contain "Feed the cat"

With explicit timeout since v3.73.0

  Given @Timeout('9s') the second item can be located at index 1 by
selector | expression       |
name     | todo-label       |
class    | todo-label       |
css      | .todo-list label |
   Then the second item should contain "Feed the cat"

Without any timeout since v3.73.0

  Given @Timeout('0s') the second item can be located at index 1 by
selector | expression       |
name     | todo-label       |
class    | todo-label       |
css      | .todo-list label |
   Then the second item should contain "Feed the cat"

Link

Learn more

Since v2.28.0

Relative Locators

<element> can be located by <selector> "<expression>" <relativeTo> <otherElement>

Binds a selector for a web element (relative to another) to the current scope with a default lookup timeout that can be overridden with the @Timeout annotation.

Where

<element> is the web element name
<selector> is the selector type, one of:
- id for selecting by id attribute
- name for selecting by name attribute
- tag name (or tag since v2.46.0) for selecting by tag name
- css selector (or css since v2.46.0) for selecting by css expression
- class name (or class since v2.46.0) for selecting by class attribute
- xpath for selecting by XPath
- link text for selecting by link text
- partial link text for selecting by partial link text
- javascript (or js since v2.46.0) for selecting by JavaScript
<expression> is the selector expression
<relativeTo> is one of
- in to select element contained in <otherElement>
- Or since v3.0.0
  - above to select element above <otherElement>
  - below to select element below <otherElement>
  - to left of to select element to the left of <otherElement>
  - to right of to select element to the right of <otherElement>
  - near to select element near <otherElement>
  - near and within <noOfPixels> pixel[s] of to select element near and within a given number of pixels of <otherElement>
    - Where <noOfPixels> is a postive integer denoting a number of pixels (max proximity to <otherElement>)
<otherElement> is the name of the web element that this one is relative to

Example

  Given the button can be located by tag "button"
    And the left field can be located by css "input" to left of the button 
   When I navigate to "https://chercher.tech/practice/relative-locators"
    And I type "I am left of the button" in the left field
   Then the left field should contain "I am left of the button"

Link

Learn more

Since v1.1.0

Relative Locators​

Relative Locators