remote/doc/marionette/SeleniumAtoms.md

   1 # Selenium atoms
   2
   3 Marionette uses a small list of [Selenium atoms] to interact with
   4 web elements.  Initially those have been added to ensure a better
   5 reliability due to a wider usage inside the Selenium project. But
   6 by adding full support for the [WebDriver specification] they will
   7 be removed step by step.
   8
   9 Currently the following atoms are in use:
  10
  11 - `getElementText`
  12 - `isElementDisplayed`
  13 - `isElementEnabled`
  14
  15 To use one of those atoms Javascript modules will have to import
  16 [atom.sys.mjs].
  17
  18 [Selenium atoms]: https://github.com/SeleniumHQ/selenium/tree/master/javascript/webdriver/atoms
  19 [WebDriver specification]: https://w3c.github.io/webdriver/webdriver-spec.html
  20 [atom.sys.mjs]: https://searchfox.org/mozilla-central/source/remote/marionette/atom.sys.mjs
  21
  22 ## Update required Selenium atoms
  23
  24 In regular intervals the atoms, which are still in use, have to
  25 be updated.  Therefore they have to be exported from the Selenium
  26 repository first, and then updated in [atom.sys.mjs].
  27
  28 ### Export Selenium Atoms
  29
  30 The canonical GitHub repository for Selenium is
  31
  32   <https://github.com/SeleniumHQ/selenium.git>
  33
  34 so make sure to have an up-to-date local copy of it. If you have to clone
  35 it first, it is recommended to specify the `--depth=1` argument, so only the
  36 last changeset is getting downloaded (which itself might already be
  37 more than 100 MB).
  38
  39 ```bash
  40 git clone --depth=1 https://github.com/SeleniumHQ/selenium.git
  41 ```
  42
  43 To export the correct version of the atoms identify the changeset id (SHA1) of
  44 the Selenium repository in the [index section] of the WebDriver specification.
  45
  46 Fetch that changeset and check it out:
  47
  48 ```bash
  49 git fetch --depth=1 origin SHA1
  50 git checkout SHA1
  51 ```
  52
  53 Now you can export all the required atoms by running the following
  54 commands. Make sure to [install bazelisk] first.
  55
  56 ```bash
  57 bazel build //javascript/atoms/fragments:get-text
  58 bazel build //javascript/atoms/fragments:is-displayed
  59 bazel build //javascript/atoms/fragments:is-enabled
  60 ```
  61
  62 For each of the exported atoms a file can now be found in the folder
  63 `bazel-bin/javascript/atoms/fragments/`.  They contain all the
  64 code including dependencies for the atom wrapped into a single function.
  65
  66 [index section]: <https://w3c.github.io/webdriver/#index>
  67 [install bazelisk]: <https://github.com/bazelbuild/bazelisk#installation>
  68
  69 ### Update atom.sys.mjs
  70
  71 To update the atoms for Marionette the `atoms.js` file has to be edited. For
  72 each atom to be updated the steps as laid out below have to be performed:
  73
  74 1. Open the Javascript file of the exported atom. See above for
  75    its location.
  76
  77 2. Add the related function name and `element` as parameters to the wrapper
  78    function, which can be found at the very beginning of the file so that it
  79    is equal to the parameters in `atom.sys.mjs`.
  80
  81 3. Copy and paste the whole contents of the file into the left textarea on
  82    <https://jsonformatter.org/json-stringify-online> to get a stringified
  83    version of all the required functions.
  84
  85 4. Copy and paste the whole contents of the right textarea, and replace the
  86    existing code for the atom in `atom.sys.mjs`.
  87
  88 ### Test the changes
  89
  90 To ensure that the update of the atoms doesn't cause a regression
  91 a try build should be run including Marionette unit tests, Firefox
  92 ui tests, and all the web-platform-tests.