git clone https://github.com/google/semantic-locators.git
The core implementation of Semantic Locators lives in the javascript
directory. The code in that directory runs in the browser, finding elements by
Semantic Locators. See javascript/DEVELOPING.md
for more details about the implementation.
Other directories such as webdriver_java
contain "wrapper libraries", allowing
for using Semantic Locators from other languages and environments. The purpose
of these libraries is to execute the javascript implementation of Semantic
Locators in the browser.
Integrating Semantic Locators with a new language/environment/library is usually
a straightforward task (<1 day of effort). The following instructions assume
you want to contribute the code back to
google/semantic-locators
.
For an example see the implementation for
Webdriver Java
.
Create the two markdown files required for new integrations:
README.md
explaining how a user can install and use the library.DEVELOPING.md
explaining how a developer can test and deploy a new version of the library.
javascript/wrapper_bin.js
contains the compiled definition of Semantic Locators to be used from wrapper
libraries. Avoid duplicating the file within this repo, instead it should be
copied as part of a build script. For example see the copy-resources
section
in
webdriver_java/pom.xml
.
Semantic locator resolution is implemented in JavaScript, so you just need a way to execute JS from your test. Testing frameworks usually provide an API for this.
See
BySemanticLocator.java
for a reference implementation. The basic flow is:
- Read
wrapper_bin.js
. - Execute the script to load Semantic Locators in the browser.
- Execute
return window.<function>.apply(null, arguments);
where<function>
is a function exported inwrapper.ts
(e.g.,return window.findElementBySemanticLocator.apply(null, arguments);
). - Parse any failures and throw an appropriate exception.
All new code must be tested. There's no need to test the full behaviour of
semantic locators, but please include smoke tests, and test things which might
break on serializing/deserializing to send to the browser. See
BySemanticLocatorTest.java
for an example.
We strongly recommended adding Continuous Integration to test and lint your
code. We use GitHub actions - see the existing workflows in
.github/workflows/*.yml
.
Open a pull request in
google/semantic-locators
so a
project maintainer can review it.
Please ask a Googler contributor to add code examples to this codelab.