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

Jump to bottom

Introduce Browser Permissions for WebDriver BiDi #425

Closed
wants to merge 28 commits into from
Closed

Introduce Browser Permissions for WebDriver BiDi #425

Changes from 1 commit
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
37f9781
Introduce Browser Permissions for WebDriver BiDi
Nov 6, 2023
437ba0b
reorder: webdriver classic to come before bidi
Nov 9, 2023
d7310e3
rename browser -> permissions module
Nov 9, 2023
22c53fa
fix <section> nesting
Nov 9, 2023
49bec97
remove user context / browsing context ID for now
Nov 14, 2023
7c9e37b
consolidate TODOs
Nov 14, 2023
5ffe92c
move items around
Nov 14, 2023
b9fed1f
indent
Nov 15, 2023
acf0653
introduce and use algorithm
Nov 16, 2023
5e37655
s/div/ol
Nov 16, 2023
163fc86
s/run the set a permission/set a permission
Nov 16, 2023
98dd229
remove permissions.PermissionDescriptor.type
Nov 16, 2023
12f450b
extension -> command, add code to TODOs
Nov 19, 2023
afd657c
<code> -> backticks
Nov 21, 2023
0242b84
lang-json -> json
Nov 21, 2023
67e7e63
drop backticks from |rootDesc| name
Nov 21, 2023
b97d2fb
may -> can
Nov 21, 2023
4a5f3fd
same origin
Nov 21, 2023
edce1e0
<a>environment settings objects</a> -> [=environment settings objects=]
Nov 21, 2023
c6eaf4c
fix algorithm markup
Nov 21, 2023
5a18fe1
remove TODOs: move them to #424
Nov 22, 2023
175f816
algorithm: add 'and return'
Nov 22, 2023
a8647fe
rename all anchors to match the convention in the bidi spec
Nov 22, 2023
fcd4cb2
null -> `null`
Nov 22, 2023
edd94bc
augment algorithm paragraph with types
Nov 22, 2023
2f2dfb2
fix algorithm variable highlighting
Nov 22, 2023
4057e4a
[=environment settings object=]
Nov 22, 2023
0183692
[=extension command URI template|URI Template=]
Nov 22, 2023
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
374 changes: 280 additions & 94 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1177,119 +1177,305 @@ <h2 id="relationship-to-permissions-policy">
permission=] or by some user agent policy.
</p>
</section>
<section data-cite="webdriver">
<section>
<h2 id="automation">
Automated testing
</h2>
<p>
For the purposes of user-agent automation and application testing, this document defines
the following <a>extension commands</a> for the [[WebDriver]] specification. It is OPTIONAL
for a user agent to support <a>extension commands</a> commands.
extensions to the [[WebDriver]] and [[WebDriver-BiDi]] specifications.
It is OPTIONAL for a user agent to support them.
</p>
<pre class='idl'>
dictionary PermissionSetParameters {
required PermissionDescriptor descriptor;
required PermissionState state;
};
</pre>
<section>
<h3 id="set-permission-command">
Set Permission
<section data-cite="webdriver-bidi webdriver">
<h3 id="automation-webdriver-bidi">
Automated testing with [[WebDriver-BiDi]]
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
</h3>
<table>
<tbody>
<tr>
<th>
HTTP Method
</th>
<th>
<a data-lt="extension command URI template">URI Template</a>
</th>
</tr>
<tr>
<td>
POST
</td>
<td>
/session/{session id}/permissions
</td>
</tr>
</tbody>
</table>
<p>
The <dfn class="export" data-dfn-for="extension commands">Set Permission</dfn>
<a>extension command</a> simulates user modification of a {{PermissionDescriptor}}'s
<a>permission state</a>.
This document defines the following [=extension modules=] for the [[WebDriver-BiDi]] specification.
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
</p>
<section>
<h4 id="extension-module-browser">
The browser Module
</h4>
<p>
The [=modules/browser=] module contains commands for
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
managing the remote end browser process.
</p>
<section>
<h5 id="extension-module-browser-definition">
Definition
</h5>
<p>
[=remote end definition=]
</p>
<pre class="cddl remote-cddl">
BrowserCommand = (
browser.setPermission
)
</pre>
</section>
<section>
<h5 id="extension-module-browser-types">
Types
</h5>
<section>
<h6 id="extension-module-type-browser-PermissionDescriptor">
The browser.PermissionDescriptor Type
</h6>
<pre class="cddl local-cddl">
browser.PermissionDescriptor = {
type: "permissionDescriptor",
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
name: text,
}
</pre>
<p>
The <code>browser.PermissionDescriptor</code> type represents a {{PermissionDescriptor}}.
</p>
</section>
<section>
<h6 id="extension-module-type-browser-PermissionState">
The browser.PermissionState Type
</h6>
<pre class="cddl local-cddl">
browser.PermissionState = "granted" / "denied" / "prompt"
</pre>
<p>
The <code>browser.PermissionState</code> type represents a {{PermissionState}}.
</p>
</section>
</section>
<section>
<h5 id="extension-module-browser-commands">
Commands
</h5>
<section>
<h6 id="extension-module-command-browser-setPermission">
The browser.setPermission Command
</h6>
<p>
The <dfn class="export" data-dfn-for="extension modules">Set Permission</dfn>
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
[=extension module=] simulates user modification of a {{PermissionDescriptor}}'s
[=permission state=].
</p>
<dl>
<dt>Command Type</dt>
<dd>
<pre class="cddl remote-cddl">
browser.setPermission = (
method: "browser.setPermission",
params: browser.SetPermissionParameters
)

browser.SetPermissionParameters = {
descriptor: browser.PermissionDescriptor,
state: browser.PermissionState,
? context: browsingContext.BrowsingContext,
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
? origin: text,
}
</pre>
</dd>
<dt>Result Type</dt>
<dd>
<pre class="cddl">
EmptyResult
</pre>
</dd>
</dl>
<div algorithm="remote end steps for permissions.setPermission">
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
<p>
The [=remote end steps=] with |session| and |command parameters| are:
</p>
<ol>
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
<li>
Let |descriptor| be the value of the <code>descriptor</code> field of
|command parameters|.
</li>
<li>
Let |state| be the value of the <code>state</code> field of |command
parameters|.
</li>
<li>
Let |context id| be the value of the <code>context</code> field of
|command parameters|.
</li>
<li>
If |context id| is not present, let |context| be the [=top-level browsing context=]
of |session|. Otherwise, let |context| be the result of [=trying=] to
[=get a browsing context=] with |context id|.
</li>
<li>
Let |permission name| be the value of the <code>name</code> field of
|descriptor| representing {{PermissionDescriptor/name}}.
</li>
<li>
[=Convert to an IDL value=] (|descriptor|, |state|) of type {{PermissionSetParameters}}.
If this conversion throws an exception, return [=error=] with [=error code=] [=invalid argument=].
</li>
<li>
Let |typedDescriptor| be the object |descriptor| refers to, <a>converted to an IDL
value</a> of |permission name|'s [=powerful
feature/permission descriptor type=]. If this throws an exception,
return [=error=] with [=error code=] [=invalid argument=].
</li>
<li>
If |state| is an inappropriate [=permission state=] for any
implementation-defined reason, return [=error=] with [=error code=] [=invalid argument=].
</li>
<li>
Let |settings| be the [=current settings object=].
</li>
<li>
Let |targets| be a [=/list=] containing all [=environment settings object=]
whose [=environment settings object/origin=] is the <a data-lt="same origin">same</a> as
the [=environment settings object/origin=] of |settings|.
</li>
<li>
Let |tasks| be an empty [=/list=].
</li>
<li>
For each [=environment settings object=] |target| in |targets|:
</li>
<ol>
<li>
[=Queue a task=] |task| on the [=permissions task source=] of |target|'s
[=relevant settings object=]'s [=environment settings object/global object=]'s
[=Window/browsing context=] to perform the following step:
</li>
<ol>
<li>
Interpret |state| as if it were the result of an invocation of [=permission state=]
for |typedDescriptor| with the argument |target| made at this moment.
</li>
</ol>
<li>
[=list/Append=] |task| to |tasks|.
</li>
</ol>
<li>
Wait for all <a>tasks</a> in |tasks| to have executed.
</li>
<li>
Return [=success=] with data null.
thiagowfx marked this conversation as resolved.
Show resolved Hide resolved
</li>
</ol>
<!-- TODO: Use origin. -->
</div>
</section>
</section>
</section>
</section>
<section data-cite="webdriver">
<h3 id="automation-webdriver">
Automated testing with [[WebDriver]]
</h3>
<p>
The <a>remote end steps</a> are:
This document defines the following <a>extension commands</a> for the [[WebDriver]] specification.
</p>
<ol>
<li>Let |parameters| be the |parameters| argument, <a>converted to an IDL value</a> of
type {{PermissionSetParameters}}. If this throws an exception, return an [=invalid
argument=] [=error=].
</li>
<li>Let |rootDesc| be |parameters|.{{PermissionSetParameters/descriptor}}.
</li>
<li>Let |typedDescriptor| be the object |rootDesc| refers to, <a>converted to an IDL
value</a> of <code>|rootDesc|.{{PermissionDescriptor/name}}</code>'s [=powerful
feature/permission descriptor type=]. If this throws an exception, return a [=invalid
argument=] [=error=].
</li>
<li>If |parameters|.{{PermissionSetParameters/state}} is an inappropriate <a>permission
state</a> for any implementation-defined reason, return a [=invalid argument=] [=error=].
<p class="note">
For example, <a>user agents</a> that define the "midi" <a>powerful feature</a> as
"always on" may choose to reject a command to set the <a>permission state</a> to
{{PermissionState/"denied"}} at this step.
</p>
</li>
<li>Let |settings| be the [=current settings object=].
</li>
<li>Let |targets| be a <a>list</a> containing all <a>environment settings objects</a>
whose [=environment settings object/origin=] is the <a data-lt="same origin">same</a> as
the [=environment settings object/origin=] of |settings|.
</li>
<li>Let |tasks| be an empty <a>list</a>.
</li>
<li>For each <a>environment settings object</a> |target| in |targets|:
<ol>
<li>
<a>Queue a task</a> |task| on the [=permissions task source=] of |target|'s
[=relevant settings object=]'s [=environment settings object/global object=]'s
[=Window/browsing context=] to perform the following step:
<ol>
<li>Interpret |parameters|.{{PermissionSetParameters/state}} as if it were the
result of an invocation of <a>permission state</a> for |typedDescriptor| with the
argument |target| made at this moment.
</li>
</ol>
</li>
<li>[=list/Append=] |task| to |tasks|.
</li>
</ol>
</li>
<li>Wait for all <a>tasks</a> in |tasks| to have executed.
</li>
<li>Return <a>success</a> with data `null`.
</li>
</ol>
<aside class="example" title="Setting a permission via WebDriver">
<section>
<h4 id="set-permission-command">
Set Permission
</h4>
<table>
<tbody>
<tr>
<th>
HTTP Method
</th>
<th>
<a data-lt="extension command URI template">URI Template</a>
</th>
</tr>
<tr>
<td>
POST
</td>
<td>
/session/{session id}/permissions
</td>
</tr>
</tbody>
</table>
<p>
To [=extension commands/set permission=] for `{name: "midi", sysex: true}` of the
[=current settings object=] of the <a>session</a> with ID 23 to "`granted`", the local
end would POST to `/session/23/permissions` with the body:
The <dfn class="export" data-dfn-for="extension commands">Set Permission</dfn>
<a>extension command</a> simulates user modification of a {{PermissionDescriptor}}'s
<a>permission state</a>.
</p>
<pre class="lang-json">
{
"descriptor": {
"name": "midi",
"sysex": true
},
"state": "granted"
}
</pre>
</aside>
<p>
The <a>remote end steps</a> are:
</p>
<ol>
<li>Let |parameters| be the |parameters| argument, <a>converted to an IDL value</a> of
type {{PermissionSetParameters}}. If this throws an exception, return an [=invalid
argument=] [=error=].
</li>
<li>Let |rootDesc| be |parameters|.{{PermissionSetParameters/descriptor}}.
</li>
<li>Let |typedDescriptor| be the object |rootDesc| refers to, <a>converted to an IDL
value</a> of <code>|rootDesc|.{{PermissionDescriptor/name}}</code>'s [=powerful
feature/permission descriptor type=]. If this throws an exception, return a [=invalid
argument=] [=error=].
</li>
<li>If |parameters|.{{PermissionSetParameters/state}} is an inappropriate <a>permission
state</a> for any implementation-defined reason, return a [=invalid argument=] [=error=].
<p class="note">
For example, <a>user agents</a> that define the "midi" <a>powerful feature</a> as
"always on" may choose to reject a command to set the <a>permission state</a> to
{{PermissionState/"denied"}} at this step.
</p>
</li>
<li>Let |settings| be the [=current settings object=].
</li>
<li>Let |targets| be a <a>list</a> containing all <a>environment settings objects</a>
whose [=environment settings object/origin=] is the <a data-lt="same origin">same</a> as
the [=environment settings object/origin=] of |settings|.
</li>
<li>Let |tasks| be an empty <a>list</a>.
</li>
<li>For each <a>environment settings object</a> |target| in |targets|:
<ol>
<li>
<a>Queue a task</a> |task| on the [=permissions task source=] of |target|'s
[=relevant settings object=]'s [=environment settings object/global object=]'s
[=Window/browsing context=] to perform the following step:
<ol>
<li>Interpret |parameters|.{{PermissionSetParameters/state}} as if it were the
result of an invocation of <a>permission state</a> for |typedDescriptor| with the
argument |target| made at this moment.
</li>
</ol>
</li>
<li>[=list/Append=] |task| to |tasks|.
</li>
</ol>
</li>
<li>Wait for all <a>tasks</a> in |tasks| to have executed.
</li>
<li>Return <a>success</a> with data `null`.
</li>
</ol>
<aside class="example" title="Setting a permission via WebDriver">
<p>
To [=extension commands/set permission=] for `{name: "midi", sysex: true}` of the
[=current settings object=] of the <a>session</a> with ID 23 to "`granted`", the local
end would POST to `/session/23/permissions` with the body:
</p>
<pre class="lang-json">
{
"descriptor": {
"name": "midi",
"sysex": true
},
"state": "granted"
}
</pre>
</aside>
</section>
</section>
</section>
<section class="appendix">
Expand Down
Loading