Overhaul the section on processing capabilities. #327

jleyba · 2016-09-06T22:37:04Z

There are several goals with these changes:

The endpoint node should either be able to satisfy all capabilities
requested by the local end, or fail to create a session.
The local end should be able to submit multiple sets of acceptable
capabilities with a clearly defined order of preference. This eliminates
the need for extra, potentially expensive, new session requests when one
set of capabilities cannot be satisfied.
Permit the definition and processing of custom capabilities, either by
the endpoint node or an intermediate node.
Preserve wire compatibility with existing implementations (i.e. the changes
do not depend on the "requiredCapabilities" and "desiredCapabilities"
parameters).

When the local end truly has no preference for the features supported by a
new session, it can simply request an empty set of capabilities.

POST /session
{"capabilities": {}}

The local end requires a specific browser (Firefox), but has no preference
for the exact value:

POST /session
{"capabilities": {"alwaysMatch":{"browserName":"firefox"}}}

The local end requires Firefox on Linux, or Chrome on Windows: the order
specified dictates in which order the endpoint should try to satisfy the
request:

POST /session
{"capabilities": {
  "firstMatch": [
    {"browserName": "firefox", "platformName": "linux"},
    {"browserName": "chrome", "platformName": "windows"}
  ]}}

Capabilities that are always required may be specified as "alwaysMatch". These
are merged with each "firstMatch" entry, eliminating the need to specify
expensive capabilities (like an encoded profile) multiple times:

POST /session
{"capabilities": {
   "alwaysMatch": {
     "browserName": "firefox",
     "profile": "base64-encoded-blob"
   },
   "firstMatch": [
     {"platformName": "linux"},
     {"platformName": "windows"}
   ]}}

Version strings are complicated. The exact matching algorithms are explicitly
left for each vendor, however, implementors are encouraged to support basic
operators to define a range of versions. That is, to request a version of
Firefox older than 48, the local end would specify:

POST /session
{"capabilities": {
   "alwaysMatch": {
     "browserName": "firefox",
     "browserVersion": "< 48"
   }}}

If an intermediate node requires additional information (i.e. auth credentials),
it MAY define custom capabilities, but it SHOULD require this information be
passed as a top level parameter:

POST /session
{"username": "test-user",
 "password": "abc123",
 "capabilities": {}}

Capabilities may never be ignored. If the endpoint does not recognize a key, it
must fail to match on those capabilities:

POST /session
{"capabilities": {
   "alwaysMatch": {
     "browserName": "firefox",
     "unrecognized-capability": 1234
   }}}

Given that unrecognized capabilities will cause new session requests to fail,
the spec requires that intermediate nodes that use capabilities for routing
remove those capabilities before forwarding the request to the selected remote
end.

This change is

There are several goals with these changes: 1. The endpoint node should either be able to satisfy all capabilities requested by the local end, or fail to create a session. 2. The local end should be able to submit multiple sets of acceptable capabilities with a clearly defined order of preference. This eliminates the need for extra, potentially expensive, new session requests when one set of capabilities cannot be satisfied. 3. Permit the definition and processing of custom capabilities, either by the endpoint node or an intermediate node. 4. Preserve wire compatibility with existing implementations (i.e. the changes do not depend on the "requiredCapabilities" and "desiredCapabilities" parameters). ---- When the local end truly has no preference for the features supported by a new session, it can simply request an empty set of capabilities. POST /session {"capabilities": {}} The local end requires a specific browser (Firefox), but has no preference for the exact value: POST /session {"capabilities": {"alwaysMatch":{"browserName":"firefox"}}} The local end requires Firefox on Linux, or Chrome on Windows: the order specified dictates in which order the endpoint should try to satisfy the request: POST /session {"capabilities": { "firstMatch": [ {"browserName": "firefox", "platformName": "linux"}, {"browserName": "chrome", "platformName": "windows"} ]}} Capabilities that are always required may be specified as "alwaysMatch". These are merged with each "firstMatch" entry, eliminating the need to specify expensive capabilities (like an encoded profile) multiple times: POST /session {"capabilities": { "alwaysMatch": { "browserName": "firefox", "profile": "base64-encoded-blob" }, "firstMatch": [ {"platformName": "linux"}, {"platformName": "windows"} ]}} Version strings are complicated. The exact matching algorithms are explicitly left for each vendor, however, implementors are encouraged to support basic operators to define a range of versions. That is, to request a version of Firefox older than 48, the local end would specify: POST /session {"capabilities": { "alwaysMatch": { "browserName": "firefox", "browserVersion": "< 48" }}} If an intermediate node requires additional information (i.e. auth credentials), it MAY define custom capabilities, but it SHOULD require this information be passed as a top level parameter: POST /session {"username": "test-user", "password": "abc123", "capabilities": {}} Capabilities may never be ignored. If the endpoint does not recognize a key, it must fail to match on those capabilities: POST /session {"capabilities": { "alwaysMatch": { "browserName": "firefox", "unrecognized-capability": 1234 }}} Given that unrecognized capabilities will cause new session requests to fail, the spec requires that intermediate nodes that use capabilities for routing remove those capabilities before forwarding the request to the selected remote end.

shs96c · 2016-09-07T05:19:44Z

webdriver-spec.html

+to describe the full feature set for a session.
+
+<p>The following table provides an overview of the standard capabilities that
+each implementation <em class="rfc2119" title="MUST">MUST</em> support.


No need for the class or title.

shs96c · 2016-09-07T05:27:25Z

I need to finish the review, but broadly in agreement with this change. I think it addresses concerns raised on IRC within the #selenium project, at face to face meetings, and in personal discussions.

shs96c · 2016-09-07T11:11:49Z

webdriver-spec.html

-     <li><p>Let <var>socks proxy port</var> be the result of <a>getting a property</a>
-      named <code>socksProxyPort</code> from <var>proxy</var>.
+  <dt>"<code>acceptSslCerts</code>"
+  <dd>False, indicating the session <em>will not</em> implicitly trust untrusted


"Boolean false" to differentiate from the string "false"

Implementation defined capabilities are only selected during the initial processing stage. These capabilities must actually be applied when initializing the new session.

juangj · 2016-09-07T21:29:23Z

webdriver-spec.html

+<td>"<code>httpProxy</code>"
+<td>string
+<td>Defines the proxy <em>hostname</em> for HTTP traffic. Alternatively, an
+  implementation <em>MAY</em> accept a hostname and port through this property.


This is nice for backwards compatibility. If a hostname:port pair is given here, AND httpProxyPort is set, which takes precedence?

I'd suggest raising an error, explaining the clash. Let the user make up their mind rather than guessing.

Required capabilities always take precedence, and it is an error to specify a capability as both a required capability and a desired capability.

The null, undefined, and "*" values are all wildcard matchers for browserName and match any name.

…pport wildcards. A wildcard value is any of null, undefined, or "*"

If the processing capabilities step fails, the new session command should return a "session not created" error that wraps the details returned from the processing capabilities.

- Default "firstMatch" parameters to [{}], not [], ensuring there is always one set of capabilities to match on. - Clarify that intermediary nodes may forward custom parameters to the remote end.

shs96c · 2016-09-12T20:36:09Z

webdriver-spec.html

+each implementation <em>MUST</em> support. An implementation <em>MAY</em> define
+additional capabilities, although it is <em>RECOMMENDED</em> that custom
+capabilities prepend the capability key with a vendor prefix, as outlined in
+[[CSS21]].


We have a section on protocol extension in the spec. Refer to the protocol extension instead? With slashes replaced by "-"? The nice feature this offers is that it suggests that each vendor's product is also included in the key, which reduces the chance of a collision.

The section on protocol extension talks about vendor prefixs used in the URI path. There's no mention of extending parameters. Should that be added?

shs96c · 2016-09-12T20:41:28Z

webdriver-spec.html

+<p>The <a>Session Timeouts Configuration</a> capability is a JSON Object nested
+within the primary capabilities. It consists of the properties listed in the
+table below. These values may be changed after creating a <a>new session</a>
+using the <a>Set Timeout</a> command.


These timeouts are all in the Set Timeout section. Refer to these rather than duplicate the information?

andreastt · 2016-09-21T15:47:24Z

@jleyba At the F2F we decided to adopt this proposal, congratulations!

There were noted several technical problems with the algorithm in the patch, but it was suggested that we would go ahead and merge it and fix these later. There is general agreement on the approach.

shs96c · 2016-10-06T14:33:26Z

Adding @AutomatedTester as an assignee, since the action item from the Lisbon F2F was for him to make some edits and then land this patch.

AutomatedTester · 2016-10-21T23:19:31Z

landed, with some updates (and I expect there to be a lot more) in d0ef240

shs96c reviewed Sep 7, 2016
View reviewed changes

shs96c mentioned this pull request Sep 7, 2016

Fix up some wording about processing capabilities. #306

Closed

jleyba added 4 commits September 7, 2016 09:22

Remove unnecessary class and title attributes

0d17b52

Differentiate between boolean false and the string "false"

350ce73

Update uses of "may" to normative "MAY"

a1cd030

Update new session steps

3cb3dcf

Implementation defined capabilities are only selected during the initial processing stage. These capabilities must actually be applied when initializing the new session.

juangj reviewed Sep 7, 2016
View reviewed changes

jleyba added 6 commits September 8, 2016 09:11

Update merge capabilities language to return an error on key conflicts

c8b54b9

Required capabilities always take precedence, and it is an error to specify a capability as both a required capability and a desired capability.

Abort capabilitity processing if the merging step fails

1bc9c47

Wildcard matching for browserName capability

6503d21

The null, undefined, and "*" values are all wildcard matchers for browserName and match any name.

browserName, browserVersion, platformName, and platformVersion all su…

09c29d8

…pport wildcards. A wildcard value is any of null, undefined, or "*"

New session command should always return errors as "session not created"

03e9e24

If the processing capabilities step fails, the new session command should return a "session not created" error that wraps the details returned from the processing capabilities.

More cleanup

bc0598d

- Default "firstMatch" parameters to [{}], not [], ensuring there is always one set of capabilities to match on. - Clarify that intermediary nodes may forward custom parameters to the remote end.

shs96c reviewed Sep 12, 2016
View reviewed changes

shs96c self-assigned this Sep 14, 2016

andreastt added this to the Level 1 milestone Sep 21, 2016

andreastt mentioned this pull request Sep 21, 2016

Expose geckodriver version in Status command mozilla/geckodriver#232

Closed

andreastt mentioned this pull request Oct 5, 2016

Change New Session to take overhauled capabilities mozilla/geckodriver#262

Closed

shs96c assigned AutomatedTester Oct 6, 2016

andreastt mentioned this pull request Oct 13, 2016

Proxy support mozilla/geckodriver#97

Closed

AutomatedTester closed this Oct 21, 2016

InkUisitor mentioned this pull request May 16, 2017

Grid does not handle w3c capabilities correctly SeleniumHQ/selenium#3808

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overhaul the section on processing capabilities. #327

Overhaul the section on processing capabilities. #327

jleyba commented Sep 6, 2016 •

edited by AutomatedTester

Loading

shs96c Sep 7, 2016

shs96c commented Sep 7, 2016

shs96c Sep 7, 2016

juangj Sep 7, 2016

shs96c Sep 8, 2016

shs96c Sep 12, 2016 •

edited

Loading

jleyba Sep 12, 2016

shs96c Sep 12, 2016

andreastt commented Sep 21, 2016

shs96c commented Oct 6, 2016

AutomatedTester commented Oct 21, 2016

Overhaul the section on processing capabilities. #327

Overhaul the section on processing capabilities. #327

Conversation

jleyba commented Sep 6, 2016 • edited by AutomatedTester Loading

shs96c Sep 7, 2016

Choose a reason for hiding this comment

shs96c commented Sep 7, 2016

shs96c Sep 7, 2016

Choose a reason for hiding this comment

juangj Sep 7, 2016

Choose a reason for hiding this comment

shs96c Sep 8, 2016

Choose a reason for hiding this comment

shs96c Sep 12, 2016 • edited Loading

Choose a reason for hiding this comment

jleyba Sep 12, 2016

Choose a reason for hiding this comment

shs96c Sep 12, 2016

Choose a reason for hiding this comment

andreastt commented Sep 21, 2016

shs96c commented Oct 6, 2016

AutomatedTester commented Oct 21, 2016

jleyba commented Sep 6, 2016 •

edited by AutomatedTester

Loading

shs96c Sep 12, 2016 •

edited

Loading