Bug 1793311 - [marionette] Fix Selenium atoms export instructions. r=…

…webdriver-reviewers,jdescottes DONTBUILD

Differential Revision: https://phabricator.services.mozilla.com/D160234

remote/doc/marionette/SeleniumAtoms.md

@@ -9,7 +9,8 @@ be removed step by step.
 Currently the following atoms are in use:
 
 - `getElementText`
-- `isDisplayed`
+- `isElementDisplayed`
+- `isElementEnabled`
 
 To use one of those atoms Javascript modules will have to import
 [atom.sys.mjs].
@@ -30,30 +31,41 @@ The canonical GitHub repository for Selenium is
 
   <https://github.com/SeleniumHQ/selenium.git>
 
-so make sure to have a local copy of it. For the cloning process
-it is recommended to specify the `--depth=1` argument, so only the
-last changeset is getting downloaded (which itself will already be
-more than 100 MB). Once the clone is ready the export of the atoms
-can be triggered by running the following commands:
+so make sure to have an up-to-date local copy of it. If you have to clone
+it first, it is recommended to specify the `--depth=1` argument, so only the
+last changeset is getting downloaded (which itself might already be
+more than 100 MB).
 
-    % cd selenium
-    % ./go
-    % python buck-out/crazy-fun/%changeset%/buck.pex build --show-output %atom%
+```bash
+git clone --depth=1 https://github.com/SeleniumHQ/selenium.git
+```
 
-Hereby `%changeset%` corresponds to the currently used version of
-buck, and `%atom%` to the atom to export. The following targets
-for exporting are available:
+To export the correct version of the atoms identify the changeset id (SHA1) of
+the Selenium repository in the [index section] of the WebDriver specification.
 
-- `//javascript/webdriver/atoms:clear-element-firefox`
-- `//javascript/webdriver/atoms:get-text-firefox`
-- `//javascript/webdriver/atoms:is-displayed-firefox`
-- `//javascript/webdriver/atoms:is-enabled-firefox`
-- `//javascript/webdriver/atoms:is-selected-firefox`
+Fetch that changeset and check it out:
+
+```bash
+git fetch --depth=1 origin SHA1
+git checkout SHA1
+```
+
+Now you can export all the required atoms by running the following
+commands. Make sure to [install bazelisk] first.
+
+```bash
+bazel build //javascript/atoms/fragments:get-text
+bazel build //javascript/atoms/fragments:is-displayed
+bazel build //javascript/atoms/fragments:is-enabled
+```
 
 For each of the exported atoms a file can now be found in the folder
-`buck-out/gen/javascript/webdriver/atoms/`.  They contain all the
+`bazel-bin/javascript/atoms/fragments/`.  They contain all the
 code including dependencies for the atom wrapped into a single function.
 
+[index section]: <https://w3c.github.io/webdriver/#index>
+[install bazelisk]: <https://github.com/bazelbuild/bazelisk#installation>
+
 ### Update atom.sys.mjs
 
 To update the atoms for Marionette the `atoms.js` file has to be edited. For

remote/marionette/atom.sys.mjs

@@ -15,9 +15,11 @@
 /** @namespace */
 export const atom = {};
 
-// The following atoms have been built from sha a6b161a159c3d581b130f03a2e6e35f577f38dec in https://github.com/seleniumhq/selenium/
+// Follow the instructions to export all the atoms:
+// https://firefox-source-docs.mozilla.org/testing/marionette/SeleniumAtoms.html
+//
+// Built from SHA1: a6b161a159c3d581b130f03a2e6e35f577f38dec
 
-// To build this use `bazel build //javascript/atoms/fragments:get-text` in the selenium repository
 atom.getElementText = function(element, window){return (function(){var k=this||self;function aa(a){return"string"==typeof a}function ba(a,b){a=a.split(".");var c=k;a[0]in c||"undefined"==typeof c.execScript||c.execScript("var "+a[0]);for(var d;a.length&&(d=a.shift());)a.length||void 0===b?c[d]&&c[d]!==Object.prototype[d]?c=c[d]:c=c[d]={}:c[d]=b}
 function ca(a){var b=typeof a;if("object"==b)if(a){if(a instanceof Array)return"array";if(a instanceof Object)return b;var c=Object.prototype.toString.call(a);if("[object Window]"==c)return"object";if("[object Array]"==c||"number"==typeof a.length&&"undefined"!=typeof a.splice&&"undefined"!=typeof a.propertyIsEnumerable&&!a.propertyIsEnumerable("splice"))return"array";if("[object Function]"==c||"undefined"!=typeof a.call&&"undefined"!=typeof a.propertyIsEnumerable&&!a.propertyIsEnumerable("call"))return"function"}else return"null";
 else if("function"==b&&"undefined"==typeof a.call)return"object";return b}function da(a,b,c){return a.call.apply(a.bind,arguments)}function ea(a,b,c){if(!a)throw Error();if(2<arguments.length){var d=Array.prototype.slice.call(arguments,2);return function(){var e=Array.prototype.slice.call(arguments);Array.prototype.unshift.apply(e,d);return a.apply(b,e)}}return function(){return a.apply(b,arguments)}}
@@ -126,8 +128,6 @@ function Xc(a,b,c,d){a=a.nodeValue.replace(/[\u200b\u200e\u200f]/g,"");a=a.repla
 function Zc(a,b,c,d,e){if(3==a.nodeType&&c)Xc(a,b,d,e);else if(W(a))if(W(a,"CONTENT")||W(a,"SLOT")){for(var f=a;f.parentNode;)f=f.parentNode;f instanceof ShadowRoot?(a=W(a,"CONTENT")?a.getDistributedNodes():a.assignedNodes(),p(a,function(g){Zc(g,b,c,d,e)})):$c(a,b)}else if(W(a,"SHADOW")){for(f=a;f.parentNode;)f=f.parentNode;if(f instanceof ShadowRoot&&(a=f))for(a=a.olderShadowRoot;a;)p(a.childNodes,function(g){Zc(g,b,c,d,e)}),a=a.olderShadowRoot}else $c(a,b)}
 function $c(a,b){a.shadowRoot&&p(a.shadowRoot.childNodes,function(c){Zc(c,b,!0,null,null)});Uc(a,b,function(c,d,e,f,g){var h=null;1==c.nodeType?h=c:3==c.nodeType&&(h=c);null!=h&&(null!=h.assignedSlot||h.getDestinationInsertionPoints&&0<h.getDestinationInsertionPoints().length)||Zc(c,d,e,f,g)})};ba("_",function(a){var b=[];Ic?$c(a,b):Wc(a,b);a=la(b,Tc);return Tc(a.join("\n")).replace(/\xa0/g," ")});; return this._.apply(null,arguments);}).apply({navigator:typeof window!='undefined'?window.navigator:null,document:typeof window!='undefined'?window.document:null}, arguments);}
 
-
-// To build this use `bazel build //javascript/atoms/fragments:is-enabled` in the selenium repository
 atom.isElementEnabled = function(element, window){return (function(){var k=this||self;function aa(a){return"string"==typeof a}function ba(a,b){a=a.split(".");var c=k;a[0]in c||"undefined"==typeof c.execScript||c.execScript("var "+a[0]);for(var d;a.length&&(d=a.shift());)a.length||void 0===b?c[d]&&c[d]!==Object.prototype[d]?c=c[d]:c=c[d]={}:c[d]=b}
 function ca(a){var b=typeof a;if("object"==b)if(a){if(a instanceof Array)return"array";if(a instanceof Object)return b;var c=Object.prototype.toString.call(a);if("[object Window]"==c)return"object";if("[object Array]"==c||"number"==typeof a.length&&"undefined"!=typeof a.splice&&"undefined"!=typeof a.propertyIsEnumerable&&!a.propertyIsEnumerable("splice"))return"array";if("[object Function]"==c||"undefined"!=typeof a.call&&"undefined"!=typeof a.propertyIsEnumerable&&!a.propertyIsEnumerable("call"))return"function"}else return"null";
 else if("function"==b&&"undefined"==typeof a.call)return"object";return b}function da(a,b,c){return a.call.apply(a.bind,arguments)}function ea(a,b,c){if(!a)throw Error();if(2<arguments.length){var d=Array.prototype.slice.call(arguments,2);return function(){var e=Array.prototype.slice.call(arguments);Array.prototype.unshift.apply(e,d);return a.apply(b,e)}}return function(){return a.apply(b,arguments)}}
@@ -203,7 +203,6 @@ H(a);var d=[];for(var e=I(c);e;e=I(c))d.push(e instanceof y?e.a:e);this.snapshot
 0>g?null:d[g]}}X.ANY_TYPE=0;X.NUMBER_TYPE=1;X.STRING_TYPE=2;X.BOOLEAN_TYPE=3;X.UNORDERED_NODE_ITERATOR_TYPE=4;X.ORDERED_NODE_ITERATOR_TYPE=5;X.UNORDERED_NODE_SNAPSHOT_TYPE=6;X.ORDERED_NODE_SNAPSHOT_TYPE=7;X.ANY_UNORDERED_NODE_TYPE=8;X.FIRST_ORDERED_NODE_TYPE=9;function Pb(a){this.lookupNamespaceURI=Lb(a)}
 function Qb(a,b){a=a||k;var c=a.Document&&a.Document.prototype||a.document;if(!c.evaluate||b)a.XPathResult=X,c.evaluate=function(d,e,f,g){return(new Ob(d,f)).evaluate(e,g)},c.createExpression=function(d,e){return new Ob(d,e)},c.createNSResolver=function(d){return new Pb(d)}}ba("wgxpath.install",Qb);ba("wgxpath.install",Qb);var Rb=pa(),Sb=ra()||u("iPod"),Tb=u("iPad"),Ub=u("Android")&&!(qa()||pa()||u("Opera")||u("Silk")),Vb=qa(),Wb=u("Safari")&&!(qa()||u("Coast")||u("Opera")||u("Edge")||u("Edg/")||u("OPR")||pa()||u("Silk")||u("Android"))&&!(ra()||u("iPad")||u("iPod"));function Y(a){return(a=a.exec(t))?a[1]:""}(function(){if(Rb)return Y(/Firefox\/([0-9.]+)/);if(v||ta||sa)return xa;if(Vb)return ra()||u("iPad")||u("iPod")?Y(/CriOS\/([0-9.]+)/):Y(/Chrome\/([0-9.]+)/);if(Wb&&!(ra()||u("iPad")||u("iPod")))return Y(/Version\/([0-9.]+)/);if(Sb||Tb){var a=/Version\/(\S+).*Mobile\/(\S+)/.exec(t);if(a)return a[1]+"."+a[2]}else if(Ub)return(a=Y(/Android\s+([0-9.]+)/))?a:Y(/Version\/([0-9.]+)/);return""})();function Z(a,b){b&&"string"!==typeof b&&(b=b.toString());return!!a&&1==a.nodeType&&(!b||a.tagName.toUpperCase()==b)};var Xb="BUTTON INPUT OPTGROUP OPTION SELECT TEXTAREA".split(" ");function Yb(a){return r(Xb,function(b){return Z(a,b)})?a.disabled?!1:a.parentNode&&1==a.parentNode.nodeType&&Z(a,"OPTGROUP")||Z(a,"OPTION")?Yb(a.parentNode):!Oa(a,function(b){var c=b.parentNode;if(c&&Z(c,"FIELDSET")&&c.disabled){if(!Z(b,"LEGEND"))return!0;for(;b=void 0!==b.previousElementSibling?b.previousElementSibling:Ja(b.previousSibling);)if(Z(b,"LEGEND"))return!0}return!1}):!0};ba("_",Yb);; return this._.apply(null,arguments);}).apply({navigator:typeof window!='undefined'?window.navigator:null,document:typeof window!='undefined'?window.document:null}, arguments);}
 
-// To build this use `bazel build //javascript/atoms/fragments:is-displayed` in the selenium repository
 atom.isElementDisplayed = function(element, window){return (function(){var k=this||self;function aa(a){return"string"==typeof a}function ba(a,b){a=a.split(".");var c=k;a[0]in c||"undefined"==typeof c.execScript||c.execScript("var "+a[0]);for(var d;a.length&&(d=a.shift());)a.length||void 0===b?c[d]&&c[d]!==Object.prototype[d]?c=c[d]:c=c[d]={}:c[d]=b}
 function ca(a){var b=typeof a;if("object"==b)if(a){if(a instanceof Array)return"array";if(a instanceof Object)return b;var c=Object.prototype.toString.call(a);if("[object Window]"==c)return"object";if("[object Array]"==c||"number"==typeof a.length&&"undefined"!=typeof a.splice&&"undefined"!=typeof a.propertyIsEnumerable&&!a.propertyIsEnumerable("splice"))return"array";if("[object Function]"==c||"undefined"!=typeof a.call&&"undefined"!=typeof a.propertyIsEnumerable&&!a.propertyIsEnumerable("call"))return"function"}else return"null";
 else if("function"==b&&"undefined"==typeof a.call)return"object";return b}function da(a,b,c){return a.call.apply(a.bind,arguments)}function ea(a,b,c){if(!a)throw Error();if(2<arguments.length){var d=Array.prototype.slice.call(arguments,2);return function(){var e=Array.prototype.slice.call(arguments);Array.prototype.unshift.apply(e,d);return a.apply(b,e)}}return function(){return a.apply(b,arguments)}}