Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added practical example of how to use capabilities #1218

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Added practical example of how to use capabilities #1218

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 61 additions & 1 deletion webdriver-spec.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2547,6 +2547,66 @@ <h3>Processing Capabilities</h3>
</ol>

</section> <!-- /Processing Capabilities -->

<aside class=example>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel that this example should go above 7.1 Proxy.

<p>Capabilities are meant for defining a failsafe matrix selection of a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/are meant for/can be used to/

browser configuration in a distributed WebDriver environment. When
communicating directly with an endpoint node (i.e. geckodriver),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

<a>capabilities</a> dictionaries are only used for carrying
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/only/primarily/

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

browser-specific configuration (i.e. <var>moz:firefoxOptions</var>);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please link to extension capabilities here.

however, when talking to an <a>intermediary node</a> multiplexer,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

intermediary node … that acts as 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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


<p>If there is a requirement to have a Firefox webdriver, with no specific
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

<pre>{
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

"alwaysMatch": {
"browserName": "firefox"
}
}</pre>

<p>If Firefosx is still a requirement, but the operating system is also
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo

to be taken into account and it must be either <code>linux</code> or
<code>windows</code>, the requirement object would be:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:


<pre>{
"alwaysMatch": {
"browserName: "firefox"
},
"firstMatch": [
{"platformName": "windows"},
{"platformName: "linux"}
]
}</pre>

<p>This system allows complex matrix selections; if the requirements
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect use of semicolon.

dictate that any browser picked must supports ignoring <a>insecure TLS
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/must supports/must support/

certificates</a>, but also that (1) if it’s Firefox, it must also support
changing the window dimensions, (2) if it's Safari, there is no
further requirements:

<pre>{
"alwaysMatch": {
"acceptInsecureCerts": true
},
"firstMatch": [
{ "browserName": "firefox", "setWindowRect":true },
{ "browserName": "safari" }
]
}</pre>
<p>Basically, the <a>intermediary node</a> will pick the first webdriver in
the network that fits the requirements listed in a
<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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would drop this entire paragraph.

</p>
</aside>

</section> <!-- /Capabilities -->

<section>
Expand Down Expand Up @@ -5365,7 +5425,7 @@ <h3>Get Element CSS Value</h3>
is obtained from <a>url variables</a>.

<dt>Otherwise
<dd> "" (empty string)
<dd> "" (empty string)
</dl>

<li>Return <a>success</a> with data <var>computed value</var>.
Expand Down