Skip to main content

Locators

Introduction​

Locators are the central piece of KWIKQA's auto-waiting and retry-ability. In a nutshell, locators represent a way to find element(s) on the page at any moment.

These are the recommended built in locators.

  • getByRole() to locate by explicit and implicit accessibility attributes.
  • getByText() to locate by text content.
  • getByLabel() to locate a form control by associated label's text.
  • getByPlaceholder() to locate an input by placeholder.
  • getByAltText() to locate an element, usually image, by its text alternative.
  • getByTitle() to locate an element by its title attribute.
  • getByTestId() to locate an element based on its data-testid attribute (other attributes can be configured).

CSS and XPath are not recommended as the DOM can often change leading to non resilient tests. Instead, try to come up with a locator that is close to how the user perceives the page such as role locators or define an explicit testing contract using test ids.

Locating elements​

KWIKQA comes with multiple built-in locators. To make tests resilient, we recommend prioritizing user-facing attributes and explicit contracts such as getByRole().

Locate by role​

The getByRole() locator reflects how users and assistive technology perceive the page, for example whether some element is a button or a checkbox. When locating by role, you should usually pass the accessible name as well, so that the locator pinpoints the exact element.

Usage

For example, consider the following DOM structure.

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

Role='heading', name='Sign up'
Role='checkbox', name='Subscribe'
Role='button', name='Submit'

Locate by text​

Find an element by the text it contains when using getByText().

Usage

For example, consider the following DOM structure.

<h3>Sign up</h3>

Text=Sign up

Locate by label​

Most form controls usually have dedicated labels that could be conveniently used to interact with the form. In this case, you can locate the control by its associated label using getByLabel().

Usage

For example, consider the following DOM structure.

<label>Username <input type="text" /></label>

Label=Username

Locate by placeholder​

Inputs may have a placeholder attribute to hint to the user what value should be entered. You can locate such an input using getByPlaceholder().

Usage

For example, consider the following DOM structure.

<input type="email" placeholder="name@example.com" />

Placeholder=name@example.com

Locate by alt text​

All images should have an alt attribute that describes the image. You can locate an image based on the text alternative using getByAltText().

Usage

For example, consider the following DOM structure.

<img alt="kwikqa logo" src="/img/kwikqa-logo.svg" width="100" />

AltText=kwikqa logo

Locate by title​

Locate an element with a matching title attribute using getByTitle().

Usage

For example, consider the following DOM structure.

<span title='kwikqa'>Best Test Automation Framework</span>

Title=kwikqa

Locate by test id​

Testing by test ids is the most resilient way of testing as even if your text or role of the attribute changes the test will still pass. QA's and developers should define explicit test ids and query them with getByTestId(). However testing by test ids is not user facing. If the role or text value is important to you then consider using user facing locators such as role and text locators.

Usage

For example, consider the following DOM structure.

<button data-testid="forms">Submit</button>

TestId=forms

Locate by CSS or XPath​

If you absolutely must use CSS or XPath locators, you can use getByCSS() or getByXPath() to create a locator that takes a selector describing how to find an element in the page.

Usage

For example

css=button
xpath=//button

Note: The css and xpath locators are not recommended as they are not resilient to DOM changes. They can break easily if elements in the page change their role, text, or position.