Skip to content

Commit

Permalink
Introduce Browser Permissions for WebDriver BiDi
Browse files Browse the repository at this point in the history
  • Loading branch information
@OrKoN
OrKoN committed Nov 28, 2023
1 parent aaff51e commit 925957d
Showing 1 changed file with 221 additions and 81 deletions.
302 changes: 221 additions & 81 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1213,118 +1213,258 @@ <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 [=extension commands=] for the [[WebDriver]] specification. It is OPTIONAL
for a user agent to support [=extension commands=] 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
</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>
<div class="algorithm">
<p>
The <dfn class="export" data-dfn-for="extension commands">Set Permission</dfn>
[=extension command=] simulates user modification of a {{PermissionDescriptor}}'s
[=permission state=].
</p>
<p>
The [=remote end steps=] are:
To <dfn data-for="WebDriver">set a permission</dfn> given a {{PermissionDescriptor}} |descriptor:PermissionDescriptor|, and a {{PermissionState}} |state:PermissionState|:
</p>
<ol>
<li>Let |parameters| be the |parameters| argument, [=converted to an IDL value=] 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, [=converted to an IDL
value=] 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 [=permission
state=] for any implementation-defined reason, return a [=invalid argument=] [=error=].
<p class="note">
For example, [=user agents=] that define the "midi" [=powerful feature=] as "always
on" may choose to reject a command to set the [=permission state=] to
{{PermissionState/"denied"}} at this step.
</p>
</li>
<li>Let |settings| be the [=current settings object=].
</li>
<li>Let |targets| be a [=list=] containing all [=environment settings objects=] 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>Let |settings| be the [=current settings object=].</li>
<li>Let |targets| be a <a>list</a> containing all [=environment settings objects=]
whose [=environment settings object/origin=] is [=same origin=] as
the [=environment settings object/origin=] of |settings|.
</li>
<li>Let |tasks| be an empty <a>list</a>.</li>
<li>For each [=environment settings object=] |target| in |targets|:
<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:
<ol>
<li>Interpret |parameters|.{{PermissionSetParameters/state}} as if it were the
result of an invocation of [=permission state=] for |typedDescriptor| with the
<li>Interpret |state| as if it were the
result of an invocation of [=permission state=] for |descriptor| with the
argument |target| made at this moment.
</li>
</ol>
</li>
<li>[=list/Append=] |task| to |tasks|.
</li>
<li>[=list/Append=] |task| to |tasks|.</li>
</ol>
</li>
<li>Wait for all [=tasks=] in |tasks| to have executed.
</li>
<li>Return [=success=] with data `null`.
</li>
<li>Wait for all <a>tasks</a> in |tasks| to have executed and return.</li>
</ol>
<aside class="example" title="Setting a permission via WebDriver">
</div>
<section data-cite="webdriver">
<h3 id="automation-webdriver">
Automated testing with [[WebDriver]]
</h3>
<p>
This document defines the following <a>extension commands</a> for the [[WebDriver]] specification.
</p>
<section>
<h4 id="webdriver-command-set-permission">
Set Permission
</h4>
<table>
<tbody>
<tr>
<th>
HTTP Method
</th>
<th>
[=extension command URI template|URI Template=]
</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 [=session=] 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
[=permission state=].
</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>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" can choose to reject a command to set the [=permission state=] to
{{PermissionState/"denied"}} at this step.
</p>
</li>
<li>Let |typedDescriptor| be the object |rootDesc| refers to, <a>converted to an IDL
value</a> of |rootDesc|.{{PermissionDescriptor/name}}'s [=powerful
feature/permission descriptor type=]. If this throws an exception, return a [=invalid
argument=] [=error=].
</li>
<li>
[=Set a permission=] with |typedDescriptor| and |parameters|.{{PermissionSetParameters/state}}.
</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="json">
{
"descriptor": {
"name": "midi",
"sysex": true
},
"state": "granted"
}
</pre>
</aside>
</section>
</section>
<section data-cite="webdriver webdriver2 webdriver-bidi">
<h3 id="automation-webdriver-bidi">
Automated testing with [[WebDriver-BiDi]]
</h3>
<p>
This document defines the following [=extension modules=] for the [[WebDriver-BiDi]] specification.
</p>
<section>
<h4 id="webdriver-bidi-module-permissions">
The permissions Module
</h4>
<p>
The <dfn>permissions</dfn> module contains commands for
managing the remote end browser permissions.
</p>
<section>
<h5 id="webdriver-bidi-module-permissions-definition">
Definition
</h5>
<p>
[=remote end definition=]
</p>
<pre class="cddl remote-cddl">
PermissionsCommand = (
permissions.setPermission
)
</pre>
</section>
<section>
<h5 id="webdriver-bidi-module-permissions-types">
Types
</h5>
<section>
<h6 id="webdriver-bidi-type-permissions-PermissionDescriptor">
The permissions.PermissionDescriptor Type
</h6>
<pre class="cddl local-cddl">
permissions.PermissionDescriptor = {
name: text,
}
</pre>
<p>
The `permissions.PermissionDescriptor` type represents a {{PermissionDescriptor}}.
</p>
</section>
<section>
<h6 id="webdriver-bidi-type-permissions-PermissionState">
The permissions.PermissionState Type
</h6>
<pre class="cddl local-cddl">
permissions.PermissionState = "granted" / "denied" / "prompt"
</pre>
<p>
The `permissions.PermissionState` type represents a {{PermissionState}}.
</p>
</section>
</section>
<section>
<h5 id="webdriver-bidi-module-permissions-commands">
Commands
</h5>
<section>
<h6 id="webdriver-bidi-command-permissions-setPermission">
The permissions.setPermission Command
</h6>
<p>
The <dfn class="export">Set Permission</dfn>
[=command=] simulates user modification of a {{PermissionDescriptor}}'s
[=permission state=].
</p>
<dl>
<dt>Command Type</dt>
<dd>
<pre class="cddl remote-cddl">
permissions.setPermission = (
method: "permissions.setPermission",
params: permissions.SetPermissionParameters
)

permissions.SetPermissionParameters = {
descriptor: permissions.PermissionDescriptor,
state: permissions.PermissionState,
}
</pre>
</dd>
<dt>Result Type</dt>
<dd>
<pre class="cddl">
EmptyResult
</pre>
</dd>
</dl>
<div class="algorithm" data-algorithm="remote end steps for permissions.setPermission">
<p>
The [=remote end steps=] with |session| and |command parameters| are:
</p>
<ol>
<li>
Let |descriptor| be the value of the `descriptor` field of
|command parameters|.
</li>
<li>
Let |permission name| be the value of the `name` field of
|descriptor| representing {{PermissionDescriptor/name}}.
</li>
<li>
Let |state| be the value of the `state` field of |command
parameters|.
</li>
<li>
If |state| is an inappropriate [=permission state=] for any
implementation-defined reason, return [=error=] with [=error code=] [=invalid argument=].
</li>
<li>
Let |typedDescriptor| be the object |descriptor| refers to, [=converted to an IDL value=] (|descriptor|, |state|) of
{{PermissionSetParameters}} |permission name|'s [=powerful feature/permission descriptor type=].
If this conversion throws an exception, return [=error=] with [=error code=] [=invalid argument=].
</li>
<li>[=Set a permission=] with |typedDescriptor| and |state|.</li>
<li>Return [=success=] with data `null`.</li>
</ol>
</d>
</section>
</section>
</section>
</section>
</section>
<section class="informative">
Expand Down

0 comments on commit 925957d

Please sign in to comment.