Added practical example of how to use capabilities #1218

mercmobily · 2018-02-02T01:52:16Z

I would have loved to have a section such as this one 12 days ago, when I saw the specs for the first time.
It's my first attempt to edit this file... so, there is certainly room for improvement.
This resolves #1215; the text is "heavily borrowed" from that issue, thanks to @andreastt

Preview | Diff

andreastt

Thanks for the patch. I think there is opportunity to tighten up the wording of this example, otherwise I think it is mostly fine. Perhaps @shs96c can take a cursory look as he is the proponent of the capabilities matching system.

I have a sense that the example guides implementations of intermediary nodes a bit too much. An intermediary node does not have to be implemented like this, even though Selenium Grid is. I would love to see a more generally written example that isn’t so specific, but I wouldn’t call this request a blocker for landing this change.

One final thing: Can you please add your name to the acknowledgement section near the bottom?

andreastt · 2018-02-02T14:21:03Z

webdriver-spec.html

@@ -2547,6 +2547,66 @@ <h3>Processing Capabilities</h3>
 </ol>

 </section> <!-- /Processing Capabilities -->
+
+<aside class=example>


I feel that this example should go above 7.1 Proxy.

andreastt · 2018-02-02T14:23:07Z

webdriver-spec.html

@@ -2547,6 +2547,66 @@ <h3>Processing Capabilities</h3>
 </ol>

 </section> <!-- /Processing Capabilities -->
+
+<aside class=example>
+  <p>Capabilities are meant for defining a failsafe matrix selection of a


s/are meant for/can be used to/

andreastt · 2018-02-02T14:23:44Z

webdriver-spec.html

+<aside class=example>
+  <p>Capabilities are meant for defining a failsafe matrix selection of a
+    browser configuration in a distributed WebDriver environment. When
+    communicating directly with an endpoint node (i.e. geckodriver),


Drop “(i.e. geckodriver)” and link <a>endpoint node</a>.

andreastt · 2018-02-02T14:24:00Z

webdriver-spec.html

+  <p>Capabilities are meant for defining a failsafe matrix selection of a
+    browser configuration in a distributed WebDriver environment. When
+    communicating directly with an endpoint node (i.e. geckodriver),
+    <a>capabilities</a> dictionaries are only used for carrying


s/only/primarily/

They could also be used by (for example) the geckodriver or the safaridriver to do something like pick a version channel to use ("canary", "release"), but I don't think that any of them actually take advantage of this possibility.

Also note that even in the case of an end point node, it might be useful to configure things differently between browser versions (perhaps different versions of plugins that depend on features only exposed/removed in particular browser versions)

andreastt · 2018-02-02T14:25:44Z

webdriver-spec.html

+    browser configuration in a distributed WebDriver environment. When
+    communicating directly with an endpoint node (i.e. geckodriver),
+    <a>capabilities</a> dictionaries are only used for carrying
+    browser-specific configuration (i.e. <var>moz:firefoxOptions</var>);


s/(i.e. moz:firefoxOptions)// as it is not defined in the spec that implementations must supply browser-specific configuration. It just so happens that Chrome and Firefox does, but this is beyond the scope of the spec.

Please link to extension capabilities here.

andreastt · 2018-02-02T14:26:18Z

webdriver-spec.html

+    communicating directly with an endpoint node (i.e. geckodriver),
+    <a>capabilities</a> dictionaries are only used for carrying
+    browser-specific configuration (i.e. <var>moz:firefoxOptions</var>);
+    however, when talking to an <a>intermediary node</a> multiplexer,


intermediary node … that acts as a multiplexer

andreastt · 2018-02-02T14:27:10Z

webdriver-spec.html

+    are used for selecting a node in this network that matches the capability
+    requirements.</p>
+
+    <p>If there is a requirement to have a Firefox webdriver, with no specific


s/to have a Firefox webdriver/to purvey a Firefox WebDriver session/

andreastt · 2018-02-02T14:29:19Z

webdriver-spec.html

+
+    <p>If Firefosx is still a requirement, but the operating system is also
+      to be taken into account and it must be either <code>linux</code> or
+      <code>windows</code>, the requirement object would be:


I would skip “If Firefosx is still a requirement” and instead say:

If the operating system is an additional requirement, and it must be either Linux or Windows, this can be defined in the firstMatch array, which will be matched iteratively in the defined order:

andreastt · 2018-02-02T14:29:32Z

webdriver-spec.html

+  ]
+}</pre>
+
+    <p>This system allows complex matrix selections; if the requirements


Incorrect use of semicolon.

andreastt · 2018-02-02T14:30:20Z

webdriver-spec.html

+    <code>firstMatch</code> entry (that is, either
+    <code>{ "browserName": "firefox", "setWindowRect": true }</code> or
+    <code>{ "browserName": "safari" }</code>), but <i>always</i> making sure
+    that <code>{ "acceptInsecureCerts": true }</code> is satisfied.


I would drop this entire paragraph.

shs96c · 2018-02-06T14:07:57Z

webdriver-spec.html

+    however, when talking to an <a>intermediary node</a> multiplexer,
+    the request will likely be forwarded to another node: <a>capabilities</a>
+    are used for selecting a node in this network that matches the capability
+    requirements.</p>


What tends to happen is that the intermediary node expands the matrix, then iterates over the merged capabilities until it finds one that matches. The request itself is seldom sent to the node, but something semantically equivalent to one of the requested capabilities is sent.

shs96c · 2018-02-06T14:10:53Z

webdriver-spec.html

+      requirements in terms of operating system, the requirement object
+      would be:</p>
+
+<pre>{


This example is incorrect. Provided the sent payload contains an object as the value of the capabilities property, the spec says it's fine to do what you'd like. In other words, a remote end can do what it likes when it sees an empty capabilities payload.

shs96c · 2018-02-06T14:11:19Z

webdriver-spec.html

+  }
+}</pre>
+
+    <p>If Firefosx is still a requirement, but the operating system is also


shs96c · 2018-02-06T14:11:46Z

webdriver-spec.html

+}</pre>
+
+    <p>This system allows complex matrix selections; if the requirements
+      dictate that any browser picked must supports ignoring <a>insecure TLS


s/must supports/must support/

shs96c · 2018-02-06T14:13:12Z

webdriver-spec.html

+  <p>Capabilities are meant for defining a failsafe matrix selection of a
+    browser configuration in a distributed WebDriver environment. When
+    communicating directly with an endpoint node (i.e. geckodriver),
+    <a>capabilities</a> dictionaries are only used for carrying


They could also be used by (for example) the geckodriver or the safaridriver to do something like pick a version channel to use ("canary", "release"), but I don't think that any of them actually take advantage of this possibility.

shs96c · 2018-02-06T14:14:28Z

webdriver-spec.html

+    browser configuration in a distributed WebDriver environment. When
+    communicating directly with an endpoint node (i.e. geckodriver),
+    <a>capabilities</a> dictionaries are only used for carrying
+    browser-specific configuration (i.e. <var>moz:firefoxOptions</var>);


Please link to extension capabilities here.

shs96c · 2018-02-06T14:17:07Z

webdriver-spec.html

+  <p>Capabilities are meant for defining a failsafe matrix selection of a
+    browser configuration in a distributed WebDriver environment. When
+    communicating directly with an endpoint node (i.e. geckodriver),
+    <a>capabilities</a> dictionaries are only used for carrying


Also note that even in the case of an end point node, it might be useful to configure things differently between browser versions (perhaps different versions of plugins that depend on features only exposed/removed in particular browser versions)

mercmobily · 2018-02-07T00:34:53Z

I have a huge commitment to wrap up on the 19th of Feb. I can get to this after then. Is that OK?
I am assuming I am expected to make changes to my PR; I have to say, it's not the easiest thing to do for me. I will do my best...

shs96c · 2018-05-14T11:45:29Z

@mercmobily there's no rush: take the time you need to do the best you can. We really appreciate the effort.

andreastt · 2018-11-05T17:24:34Z

In the meantime I’ve taken some time to document WebDriver capabilities on MDN: https://developer.mozilla.org/en-US/docs/Web/WebDriver/Capabilities

Do we still think it’s worthwhile adding the examples from this PR to the specification document? If so, I can resurrect the PR if @mercmobily doesn’t have the time to finish it.

mercmobily · 2018-11-05T21:29:09Z

Honest hat on, I haven't worked on webdrivers/etc. since then, and I don't think I'd be able to apply the required changes.
For what it's worth, I think it would be great to have a practical example.

christian-bromann · 2018-11-05T21:33:11Z

@mercmobily @andreastt I would be happy to take over the work @mercmobily has started. I think this is valueable.

mercmobily · 2018-11-05T22:12:17Z

Hi, Thank you Christian -- regardless of whether this gets pushed or not Merc.

…

On Tue, 6 Nov 2018 at 05:33, Christian Bromann ***@***.***> wrote: @mercmobily <https://github.com/mercmobily> @andreastt <https://github.com/andreastt> I would be happy to take over the work @mercmobily <https://github.com/mercmobily> has started. I think this is valueable. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1218 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACB7Xlf9otb-Y1EeMhOggVgb5xQDqJWMks5usK6bgaJpZM4R2kBC> .

--

Added practical example of how to use capabilities

b682431

mercmobily requested review from andreastt, AutomatedTester, jgraham and shs96c as code owners February 2, 2018 01:52

mercmobily mentioned this pull request Feb 2, 2018

Please explain in simple words how firstMatch and alwaysMatch work #1215

Closed

andreastt requested changes Feb 2, 2018

View reviewed changes

shs96c requested changes Feb 6, 2018

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added practical example of how to use capabilities #1218

Added practical example of how to use capabilities #1218

mercmobily commented Feb 2, 2018 •

edited by pr-preview bot

Loading

andreastt left a comment

andreastt Feb 2, 2018

andreastt Feb 2, 2018

andreastt Feb 2, 2018

andreastt Feb 2, 2018

shs96c Feb 6, 2018

shs96c Feb 6, 2018

andreastt Feb 2, 2018

shs96c Feb 6, 2018

andreastt Feb 2, 2018

andreastt Feb 2, 2018

andreastt Feb 2, 2018

andreastt Feb 2, 2018

andreastt Feb 2, 2018

shs96c Feb 6, 2018

shs96c Feb 6, 2018

shs96c Feb 6, 2018

shs96c Feb 6, 2018

shs96c Feb 6, 2018

shs96c Feb 6, 2018

shs96c Feb 6, 2018

mercmobily commented Feb 7, 2018

shs96c commented May 14, 2018

andreastt commented Nov 5, 2018

mercmobily commented Nov 5, 2018

christian-bromann commented Nov 5, 2018

mercmobily commented Nov 5, 2018 via email

Added practical example of how to use capabilities #1218

Are you sure you want to change the base?

Added practical example of how to use capabilities #1218

Conversation

mercmobily commented Feb 2, 2018 • edited by pr-preview bot Loading

andreastt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mercmobily commented Feb 7, 2018

shs96c commented May 14, 2018

andreastt commented Nov 5, 2018

mercmobily commented Nov 5, 2018

christian-bromann commented Nov 5, 2018

mercmobily commented Nov 5, 2018 via email

mercmobily commented Feb 2, 2018 •

edited by pr-preview bot

Loading