Locators

Locators are special mechanisms used to find elements on a web page. They allow to locate specific elements such as buttons, input fields, or links to interact with them.

The Selenium webdriver methods use tuples (By, query) to find elements, where By is one of the supported locator strategies and query is the query for that strategy. About Selenium supported locator strategies you can read here.

Pomcorn implements its own classes for defining web page elements - Locators. XPath was chosen as the only strategy because it eliminated the need to specify the type of strategy and also made it easier to create relative locators.

Note

Others prefer NOT to use XPath because the DOM can change frequently and tests will crash. Therefore, to make the tests more stable, we have implemented a number of locators that follow the same logic as the other strategies (search by css, by tag name, by classes, by properties, etc.), but based on XPath.

Interfaces

        classDiagram
  Locator <|-- XPathLocator
  XPathLocator <|-- TInitLocator
  XPathLocator <|-- TLocator
  XPathLocator <|-- ElementWithTextLocator
  XPathLocator <|-- InputByLabelLocator
  XPathLocator <|-- PropertyLocator
  XPathLocator <|-- TagNameLocator
  XPathLocator <|-- TextAreaByLabelLocator

  PropertyLocator <|-- ClassLocator
  PropertyLocator <|-- DataTestIdLocator
  PropertyLocator <|-- IdLocator
  PropertyLocator <|-- NameLocator
  ElementWithTextLocator <|-- ButtonWithTextLocator
    

* you can zoom it

class pomcorn.locators.Locator(by: str, query: str)

Base locator for looking for elements in page.

__init__(by: str, query: str)

Init locator.

Parameters:

• by – One of the supported selenium locator strategies.

• query – Query for the strategy.

class pomcorn.locators.XPathLocator(query: str)

Locator to looking for elements in page by XPath.

XPathLocator overrides methods for / and // operators to provide “path-like” syntax for locators.

So we can use / and // operators to concatenate locators query by / and // accordingly:

# //*[@class=”class”]

class_locator = ClassLocator(“class”)

# //container[@prop=”value”]

property_locator = PropertyLocator(

prop=”prop”, value=”value”, container=”container”,

)

# //*[@class=”class”]/container[@prop=”value”]

class_locator / property_locator

# //*[@class=”class”]//container[@prop=”value”]

class_locator // property_locator

To extend query of locator you can use extend_query method:

new_locator = class_locator.extend_query(“[@some_prop=’value’]”)

new_locator.query # //*[@class=”class”][@some_prop=”value”]

All custom locators that inherit XPathLocator should be independent and start with //.

divider = '//'

__init__(query: str)

Set related query for locators concatenation.

Parameters:

query – Query for the XPath locator strategy.

extend_query(extra_query: str) → XPathLocator

Return new XPathLocator with extended query.

contains(text: str, exact: bool = False) → XPathLocator

Return new XPathLocator with search on contained text.

This is shortcut for the commonly used .extend_query(f”[contains(., ‘{text}’)]).

Parameters:

• text – The text that should be inside the tag.

• exact – Specify whether the text being searched must match exactly. By default, the search is based on a partial match.

prepare_relative_locator(other: XPathLocator, separator: Literal['/', '//'] = '/') → XPathLocator

Prepare relative locator base on queries of two locators.

If one of parent and other locator queries is empty, the method will return only the filled one.

Parameters:

• other – Child locator object.

• separator – Literal which will placed between locators queries - “/” used to select nearest children of current node and “//” used to select all descendants (children, grandchildren, great-grandchildren, etc.) of current node, regardless of their level in hierarchy.

Raises:

ValueError – If parent and child locators queries are empty.

class pomcorn.locators.xpath_locators.TagNameLocator(tag: str)

Locator to look for elements with tag by Xpath.

__init__(tag: str)

Init XPathLocator.

Specify the query as the string //tag, where tag is the name of the html tag.

class pomcorn.locators.xpath_locators.PropertyLocator(prop: str, value: str, container: str = '*', exact: bool = False)

Locator to look for elements with property by XPath.

__init__(prop: str, value: str, container: str = '*', exact: bool = False)

Init XPathLocator.

Parameters:

• prop – The name of the html tag property.

• value – The value of property.

• container – The tag in which the property should be. The default is *, which means “any tag”.

• exact – Specify whether the value of the property being searched must match exactly. By default, the search is based on a partial match of the value.

class pomcorn.locators.xpath_locators.DataTestIdLocator(value: str, container: str = '*')

Locator to look for elements with custom testid property.

Inherits from PropertyLocator and sets the default values prop="data-testid" and exact=True.

__init__(value: str, container: str = '*')

Init XPathLocator.

Parameters:

• value – The value of testid property.

• container – The tag in which the property should be. The default is *, which means “any tag”.

class pomcorn.locators.xpath_locators.IdLocator(value: str, container: str = '*')

Locator to look for elements with ID by Xpath.

Inherits from PropertyLocator and sets the default values prop="id" and exact=True.

__init__(value: str, container: str = '*')

Init XPathLocator.

Parameters:

• value – The value of id property.

• container – The tag in which the property should be. The default is *, which means “any tag”.

class pomcorn.locators.xpath_locators.NameLocator(value: str, container: str = '*')

Locator to look for elements with name by Xpath.

Inherits from PropertyLocator and sets the default values prop="name" and exact=True.

__init__(value: str, container: str = '*')

Init XPathLocator.

Parameters:

• value – The value of name property.

• container – The tag in which the property should be. The default is *, which means “any tag”.

class pomcorn.locators.xpath_locators.ElementWithTextLocator(text: str, element: str = '*', exact: bool = False)

Locator to look for elements with text by XPath.

__init__(text: str, element: str = '*', exact: bool = False)

Init XPathLocator.

Parameters:

• text – The text that should be inside the tag.

• element – The tag in which the text should be. The default is *, which means “any tag”.

• exact – Specify whether the value of the property being searched must match exactly. By default, the search is based on a partial match of the value.

class pomcorn.locators.xpath_locators.ClassLocator(class_name: str, container: str = '*', exact: bool = False)

Locator to look for elements with partial class by XPath.

Inherits from PropertyLocator and sets the default value prop="class".

__init__(class_name: str, container: str = '*', exact: bool = False)

Init XPathLocator.

Parameters:

• class_name – The name of tag class.

• container – The tag in which the property should be. The default is *, which means “any tag”.

• exact – Specify whether the value of the property being searched must match exactly. By default, the search is based on a partial match of the value.

class pomcorn.locators.xpath_locators.ButtonWithTextLocator(text: str, exact: bool = False)

Locator to looking for button with text by XPath.

Inherits from ElementWithTextLocator and sets the default value element="button".

__init__(text: str, exact: bool = False)

Init XPathLocator.

Parameters:

• text – The text that should be inside the button tag.

• exact – Specify whether the value of the property being searched must match exactly. By default, the search is based on a partial match of the value.

class pomcorn.locators.xpath_locators.InputInLabelLocator(label: str)

Locator to looking for input with label by XPath.

Specify the query as the string //label[contains(., "label")]//input, where label is the text of the input label.

# Example
<label>Title</label>
    <input value="Value">
</label>

__init__(label: str)

Init XPathLocator.

class pomcorn.locators.xpath_locators.InputByLabelLocator(label: str)

Locator to looking for input next to label by XPath.

Specify the query as the string //label[contains(., "label")]/following-sibling::input, where label is the text of the input label.

# Example
<div>
    <label for="InputWithLabel">Title</label>
    <input id="InputWithLabel" value="Value">
</div>

__init__(label: str)

Init XPathLocator.

class pomcorn.locators.xpath_locators.TextAreaByLabelLocator(label: str)

Locator to looking for textarea with label by XPath.

Specify the query as the string //*[label[contains(text(), "{label}")]]/textarea, where label is the text of the textarea label.

__init__(label: str)

Init XPathLocator.