Semantic Locators

Semantic Locators let you specify HTML elements in code similar to how you might describe them to a human. For example, a create button might have a semantic locator of {button 'Create'}.

Semantic Locators are stable, readable, enforce accessibility, and can be auto-generated.

Just want to get started writing semantic locators? See the tutorial, or read on for an introduction.

Getting started

See the getting started instructions for your environment:

• JavaScript/TypeScript in the browser
• Java WebDriver
• Python WebDriver
• .NET WebDriver
• Something else? Adding support for a new platform is simple. See DEVELOPING.md for instructions.

Examples

HTML	Semantic Locator
<button>OK</button>	{button 'OK'}
<div role="tab" aria-label="Meeting">	{tab 'Meeting'}
<ul><li>	{list} {listitem}
<button>User id: 32659768187</button>	{button 'User id: *'}
<div role="checkbox" aria-checked="false"></div>	{checkbox checked:false}

Why Semantic Locators?

As the name suggests, Semantic Locators find elements based on their semantics. This has a number of benefits over other types of locators.

Semantics

First we should define the term "semantics".

The semantics of an element describe its meaning to a user. Is it a button or a checkbox? Will it submit or cancel an operation? When using assistive technologies like screen readers, the semantics of an element determine how it is described to users.

There are many semantically equivalent ways to implement OK buttons. The following elements are all matched by the semantic locator {button 'OK'}.

<button>OK</button>
<button aria-label="OK">...</button>
<div role="button">OK</div>
<input type="submit" aria-label="OK">
<button aria-labelledby="other_element">...</button><div id="other_element">OK</div>
<button id="element_id">...</button><label for="element_id">OK</label>

To be precise, button refers to the ARIA role expressed by the element. 'OK' refers to the accessible name of the element.

What benefits does finding elements by their semantics provide?

Stability

Semantic locators are less brittle to user-invisible changes. Matching semantics abstracts away implementation details. For example if

<div><span><div><div><div role="button" aria-label="Send">

changes to

<div><button>Send

then {button 'Send'} will still work as a locator.

Accessibility

Semantic locators can help surface missing or broken semantics, as locators won't exist for inaccessible elements. For example, if your submit button has an incorrect accessible name, the error from Semantic Locators can reveal the bug:

> findBySemanticLocator('{button "Submit"}');

Error:
Didn't find any elements matching semantic locator {button “Submit”}.
1 element with an ARIA role of button was found.
However it didn't have an accessible name of "Submit".
Accessible names found: ["right_arrow.png"].

Readability

Semantics are meant for human consumption, and so are semantic locators. They're very similar to how a screen-reader would announce elements to a non-sighted user.

XPath: //input[@type='submit' and @aria-label='Send']

Semantic Locator: {button 'Send'}

Cheap to produce

Semantic Locators can be automatically generated from an interactive playground, a Chrome Extension, or easily written with the help of browser dev tools. See the tutorial for a guide.

Why not Semantic Locators?

You don't care about a11y

Semantic locators rely on HTML accessibility (a11y) features to find elements. Therefore, if your app is inaccessible to a screen reader it is unlikely to work with semantic locators. If you're looking to improve a11y, introducing semantic locators can be a great strategy!

Most modern web frameworks are accessible by default, and if you use semantic HTML (e.g., <button>, <input> and <li> rather than <div> for everything) your app will benefit from native a11y features. So you may not have any additional work to do.

If you haven't considered making your site accessible yet, now is a great time to do so! Consider that 1 billion people worldwide (~15%) have a disability and may have difficulty using apps written without a11y in mind. Accessible apps are also more usable for everyone. And if that's not enough of an incentive, a11y is a legal requirement in many jurisdictions.

You have cross-language requirements for your tests

...and no way to access localized strings from your tests.

Semantic locators use the text that a screen reader would read to a human, so are usually locale-specific. If you want to test in multiple languages, you will most likely have to adapt your locators.

See the faq for a discussion of this requirement and potential solutions.

Disclaimer

This is not an officially supported Google product.