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. Remove the contained license header, which can be found somewhere
  78    in the middle of the file.
  79
  80 3. Update the parameters of the wrapper function (at the very top)
  81    so that those are equal with the used parameters in `atom.sys.mjs`.
  82
  83 4. Copy the whole content of the file, and replace the existing
  84    code for the atom in `atom.sys.mjs`.
  85
  86 ### Test the changes
  87
  88 To ensure that the update of the atoms doesn't cause a regression
  89 a try build should be run including Marionette unit tests, Firefox
  90 ui tests, and all the web-platform-tests.