Git Product home page Git Product logo

semantic-locators's Introduction

Semantic Locators

Magnifying glass icon

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:

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.

semantic-locators's People

Contributors

alexlloyd0 avatar concavelenz avatar dependabot[bot] avatar engelsdamien avatar jordan-mace avatar lauraharker avatar olegnitz avatar rchen152 avatar shicks avatar thompsonja avatar yilei avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

semantic-locators's Issues

Implement dotnet integration

Describe the feature
An integration of semantic-locators in dotnet, following the same logic as the java integration.

Use case
Selenium provides dotnet bindings

Support iframe

Describe the feature
Please support semantic-locators works in iframe.
accname used to use node instanceof HTMLElement, that will not work on elements that belong to other windows/frames.
It seems that this problem got fixed, but never publish to npm?
google/accname@466d7e9

Use case
I'm trying to add a custom command to cypress, and cypress runs everything inside an iframe

Awesome library. Thx. @AlexLloyd0

Support locator combinators

Consider adding combinators to allow for locators to find the {cell} {button 'Mark resolved'} which is a sibling of a {cell 'Buy milk'}.

This would add significant complexity to the language and implementation. It may never be a good idea to implement, but this issue can be used to track any use cases.

Error [ERR_INVALID_PACKAGE_TARGET]: Invalid "exports" main target "dist/src/semantic_locators.js"

Describe the bug
Invalid exports path in package.json, cause require module failed.

According to this documentation , "All paths defined in the "exports" must be relative file URLs starting with ./.".
However we got

  "exports": {
    ".": {"require": "dist/src/semantic_locators.js"},
    "./gen":{"require": "dist/src/gen/index.js"}
  },

image

@
To Reproduce
Steps to reproduce the behavior:
When ever require semantic locator into a js file, and run it directly in node (without any other module resolver , like webpack , or even jest)
this log come along:

Error [ERR_INVALID_PACKAGE_TARGET]: Invalid "exports" main target "dist/src/semantic_locators.js" defined in the package config /xxx/node_modules/semantic-locator/package.json;
 targets must start with "./"

Expected behavior
can be required successfully.

Screenshots
image

Environment (please complete the following information):

  • OS: [e.g. Windows]
  • Browser and version: [e.g. Chrome v87]
  • Semantic Locators environment [e.g. JavaScript, Java WebDriver, All]

Additional context
Add any other context about the problem here.

Support for Selenium 4 in Python

Describe the feature
Allow for using semantic locators with Selenium 4 in a Python environment.

Use case
I want to use the element.accessbile_name feature from Selenium 4 alongside this library.

Steps to reproduce
Create a requirements.txt

selenium==4
semantic-locators==2.1.0

Call pip3 install -r requirements.txt

Causes the following error:

ERROR: Cannot install selenium==4 and semantic-locators==2.1.0 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested selenium==4
    semantic-locators 2.1.0 depends on selenium<4.0.0 and >=3.141.0

Set up testing.

Are there supposed to be testing toolings for this project?

Add dotnet to Actions

Currently the GitHub actions does not perform a build of dotnet, this removes visibility over breaking changes.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.