Introduce "Automation" section (#151)

index.bs

@@ -44,7 +44,19 @@ spec: sensors; urlPrefix: https://w3c.github.io/sensors/#
 spec: manifest; urlPrefix: https://w3c.github.io/manifest/#
     type: dfn
         text: install; url: dfn-install
-
+spec: webdriver; urlPrefix: https://w3c.github.io/webdriver/webdriver-spec.html#
+    type: dfn
+        text: current browsing context; url: dfn-current-browsing-context
+        text: WebDriver error; url: dfn-error
+        text: WebDriver error code; url: dfn-error-code
+        text: extension command; url: dfn-extension-commands
+        text: extension command name; url: dfn-extension-command-name
+        text: extension command prefix; url: dfn-extension-command-prefix
+        text: invalid argument; url: dfn-invalid-argument
+        text: local end; url: dfn-local-end
+        text: remote end steps; url: dfn-remote-end-steps
+        text: session; url: dfn-session
+        text: success; url: dfn-success
 </pre>
 <pre class="link-defaults">
 spec: dom
@@ -60,6 +72,10 @@ spec: html
 spec: storage
     type: enum-value
         for: PermissionName; text: "persistent-storage"
+spec: infra
+    type: dfn
+        text: list
+        for: list; text: append
 spec: ui-events
     type: dfn
         text: user agent
@@ -974,6 +990,119 @@ spec: webidl
     </p>
   </section>
 </section>
+<section>
+  <h2 id="automation">
+    Automation
+  </h2>
+  <p>
+    For the purposes of user-agent automation and application testing, this
+    document defines the following <a>extension command</a> for the
+    [[WebDriver]] specification.
+  </p>
+
+  <pre class='idl'>
+    dictionary PermissionSetParameters {
+      required PermissionDescriptor descriptor;
+      required PermissionState state;
+      boolean oneRealm = false;
+    };
+  </pre>
+
+  <section>
+    <h3 id="set-permission-command">
+      Set Permission
+    </h3>
+    <table>
+      <tbody>
+        <tr>
+          <th>HTTP Method</th>
+          <th><a lt="extension command prefix">Prefix</a></th>
+          <th><a lt="extension command name">Name</a></th>
+        </tr>
+        <tr>
+          <td>POST</td>
+          <td>/session/{session id}/permissions</td>
+          <td>set</td>
+        </tr>
+      </tbody>
+    </table>
+    <p>The <dfn>Set Permission</dfn> <a>extension command</a> simulates user
+    modification of a {{PermissionDescriptor}}'s <a>permission state</a>.</p>
+    <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 a <a>WebDriver error</a> with <a>WebDriver error
+        code</a> <a>invalid argument</a>.
+      <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 <a>permission
+        descriptor type</a>. If this throws an exception, return a <a>WebDriver
+        error</a> with <a>WebDriver error code</a> <a>invalid
+        argument</a>.</li>
+      <li>If |parameters|.{{PermissionSetParameters/state}} is an inappropriate
+        <a>permission state</a> for any implementation-defined reason, return a
+        <a>WebDriver error</a> with <a>WebDriver error code</a> <a>invalid
+        argument</a>.
+        <p class="note">
+          For example, <a>user agents</a> that define the {{"midi"}}
+          <a>feature</a> as "always on" may choose to reject command
+          to set the <a>permission state</a> to {{"denied"}} at this step.
+        </p>
+      </li>
+      <li>Let |settings| be the <a>environment settings object</a> of the
+        <a>current browsing context</a>'s <a>active document</a>.</li>
+      <li>If |settings| is a <a>non-secure context</a> and
+        <code>|rootDesc|.{{PermissionDescriptor/name}}</code> isn't <a>allowed
+        in non-secure contexts</a>, return a <a>WebDriver error</a> with
+        <a>WebDriver error code</a> <a>invalid argument</a>.</li>
+      <li>If |parameters|.{{PermissionSetParameters/oneRealm}} is true, let
+        |targets| be a <a>list</a> whose sole member is |settings|.</li>
+      <li>Otherwise, let |targets| be a <a>list</a> containing all
+        <a>environment settings objects</a> whose [=environment settings
+        object/origin=] is the <a lt="same origin">same</a> as the
+        [=environment settings object/origin=] of |settings|.</li>
+      </li>
+      <li>Let |tasks| be an empty <a>list</a>.
+      <li>
+        For each <a>environment settings object</a> |target| in |targets|:
+        <ol>
+          <li><a>Queue a task</a> |task| on the <a>permission task source</a>
+            of |target|'s [=environment settings object/responsible browsing
+            context=] to perform the following step:</li>
+            <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><a>Append</a> |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>
+    <div class="example">
+      To set permission for <code>{name: {{"midi"}}, sysex: true}</code> of the
+      <a>current browsing context</a> of the <a>session</a> with ID 23 to
+      "`granted`", the <a>local end</a> would POST to
+      `/session/23/permissions/set` with the body:
+
+      <pre class="lang-json">
+      {
+        "descriptor": {
+          "name": "midi",
+          "sysex": true
+        },
+        "state": "granted"
+      }
+      </pre>
+    </div>
+  </section>
+</section>
 <section class='non-normative'>
   <h2 id="examples">
     Examples