Add automation support via WebDriver (#141)

This PR integrates with the automation concepts defined in
https://w3c.github.io/device-posture/#automation to allow changing
device posture through the WebDriver extension commands defined there.

Set device posture WebDriver extension will enable overriding posture
defined by hardware.

Clear device posture WebDriver extension removes device posture override
and returns device posture control back to hardware.

Fixes #140

index.html

@@ -188,6 +188,41 @@ <h3>
           </tr>
         </tbody>
       </table>
+      <p>
+        [=Top-level traversables=] must have the following internal slots:
+      </p>
+      <table class="simple">
+        <thead>
+          <tr>
+            <th>
+              Internal slot
+            </th>
+            <th>
+              Description
+            </th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>
+              <dfn data-dfn-for="top-level traversable">[[\PostureOverride]]
+              </dfn>
+            </td>
+            <td>
+              Posture to override posture defined by hardware. Used in
+              automation. Possible values:
+              <ul>
+                <li>"{{DevicePostureType/continuous}}"
+                </li>
+                <li>"{{DevicePostureType/folded}}"
+                </li>
+                <li><code>null</code>: Used when posture is defined by hardware.
+                </li>
+              </ul>
+            </td>
+          </tr>
+        </tbody>
+      </table>
     </section>
     <section data-dfn-for="Navigator">
       <h2 id="extensions-to-the-navigator-interface">
@@ -445,6 +480,12 @@ <h2>
           {{Document}} |document:Document| are as follows:
         </p>
         <ol class="algorithm">
+          <li>Let |topLevelTraversable| be |document|'s [=relevant global
+          object=]'s [=navigable=]'s [=top-level traversable=].
+          </li>
+          <li>If |topLevelTraversable|.<a data-link-for="top-level traversable">
+          [[\PostureOverride]]</a> is non-null, return it.
+          </li>
           <li>Return a {{DevicePostureType}} value determined in an
           [=implementation-defined=] way based on the current hinge angle
           value, current <a data-cite=
@@ -690,6 +731,152 @@ <h2>
         </li>
       </ul>
     </section>
+    <section>
+      <h2>
+        Automation
+      </h2>
+      <p>
+        The Device Posture API pose a challenge to test authors, as fully
+        exercising interface requires physical hardware devices. To address this
+        challenge this document defines a [[WEBDRIVER2]] [=extension commands=]
+        that allows users to control the reported device posture and simulate a
+        real device.
+      </p>
+      <h3>
+        Extension Commands
+      </h3>
+      <h4>
+        Set device posture
+      </h4>
+      <table class="simple">
+        <tr>
+          <th>
+            HTTP Method
+          </th>
+          <th>
+            [=extension command URI Template|URI Template=]
+          </th>
+        </tr>
+        <tr>
+          <td>
+            POST
+          </td>
+          <td>
+            /session/{session id}/deviceposture
+          </td>
+        </tr>
+      </table>
+      <p>
+        This [=extension command=] changes device posture to a specific
+        {{DevicePostureType}}.
+      </p>
+      <table class="simple">
+        <caption>
+          Properties of the parameters argument used by this algorithm
+        </caption>
+        <tr>
+          <th>
+            Parameter name
+          </th>
+          <th>
+            Value type
+          </th>
+          <th>
+          Required
+          </th>
+        </tr>
+        <tr>
+          <td>
+            posture
+          </td>
+          <td>
+            String
+          </td>
+          <td>
+            yes
+          </td>
+        </tr>
+      </table>
+      <p>
+        The [=remote end steps=] are:
+      </p>
+      <ol class="algorithm" data-cite="WEBDRIVER2">
+        <li>Let |posture| be the result of invoking
+        <a data-cite="!WEBDRIVER2#dfn-getting-properties">get a property</a>
+        "posture" from |parameters|.
+        </li>
+        <li>If |posture| is not a [=string=], return [=error=] with
+        [=error code|WebDriver error code=] [=invalid argument=].
+        </li>
+        <li>If |posture| is neither "{{DevicePostureType/continuous}}" nor
+        "{{DevicePostureType/folded}}", return [=error=] with
+        [=error code|WebDriver error code=] [=invalid argument=].
+        </li>
+        <li>Let |topLevelTraversable| be the
+        <a data-cite="webdriver2/#dfn-current-browsing-context">current browsing
+        context</a>'s [=browsing context/top-level traversable=].
+        </li>
+        <li>Set |topLevelTraversable|.<a data-link-for="top-level traversable">
+        [[\PostureOverride]]</a> to |posture|.
+        </li>
+        <li>Let |document| be |topLevelTraversable|'s [=navigable/active
+        document=].
+        </li>
+        <li>Invoke [=device posture change steps=] with |document|.
+        </li>
+        <li>Return [=success=] with data <code>null</code>.
+        </li>
+      </ol>
+      <h4>
+        Clear device posture
+      </h4>
+      <table class="simple">
+        <tr>
+          <th>
+            HTTP Method
+          </th>
+          <th>
+            [=extension command URI Template|URI Template=]
+          </th>
+        </tr>
+        <tr>
+          <td>
+            DELETE
+          </td>
+          <td>
+            /session/{session id}/deviceposture
+          </td>
+        </tr>
+      </table>
+      <p>
+        This [=extension command=] removes device posture override and returns
+        device posture control back to hardware.
+      </p>
+      <p>
+        The [=remote end steps=] are:
+      </p>
+      <ol class="algorithm">
+        <li>Let |topLevelTraversable| be the
+        <a data-cite="webdriver2/#dfn-current-browsing-context">current browsing
+        context</a>'s [=browsing context/top-level traversable=].
+        </li>
+        <li>If |topLevelTraversable|.<a data-link-for="top-level traversable">
+        [[\PostureOverride]]</a> is <code>null</code>, return [=success=] with
+        data <code>null</code>.
+        </li>
+        <li>Set |topLevelTraversable|.<a data-link-for="top-level traversable">
+        [[\PostureOverride]]</a> to
+        <code>null</code>.
+        </li>
+        <li>Let |document| be |topLevelTraversable|'s [=navigable/active
+        document=].
+        </li>
+        <li>Invoke [=device posture change steps=] with |document|.
+        </li>
+        <li>Return [=success=] with data <code>null</code>.
+        </li>
+      </ol>
+    </section>
     <section id="examples" class="informative">
       <h2>
         Examples