From 925957d5032cf8fd4bff865f50e951497791fe25 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Mon, 27 Nov 2023 08:49:56 +0100 Subject: [PATCH] Introduce Browser Permissions for WebDriver BiDi --- index.html | 302 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 221 insertions(+), 81 deletions(-) diff --git a/index.html b/index.html index bd3354d..1e6df43 100644 --- a/index.html +++ b/index.html @@ -1213,14 +1213,14 @@

permission=] or by some user agent policy.

-
+

Automated testing

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. 

         dictionary PermissionSetParameters {
@@ -1228,103 +1228,243 @@ 

           required PermissionState state;
         };
-
-

- Set Permission -

- - - - - - - - - - - -
- HTTP Method - - URI Template -
- POST - - /session/{session id}/permissions -
+

- The Set Permission - [=extension command=] simulates user modification of a {{PermissionDescriptor}}'s - [=permission state=]. -

-

- The [=remote end steps=] are: + To set a permission given a {{PermissionDescriptor}} |descriptor:PermissionDescriptor|, and a {{PermissionState}} |state:PermissionState|:

    -
  1. Let |parameters| be the |parameters| argument, [=converted to an IDL value=] of type - {{PermissionSetParameters}}. If this throws an exception, return an [=invalid argument=] - [=error=]. -
    2. -
  2. Let |rootDesc| be |parameters|.{{PermissionSetParameters/descriptor}}. -
    3. -
  3. Let |typedDescriptor| be the object |rootDesc| refers to, [=converted to an IDL - value=] of |rootDesc|.{{PermissionDescriptor/name}}'s [=powerful - feature/permission descriptor type=]. If this throws an exception, return a [=invalid - argument=] [=error=]. -
    4. -
  4. If |parameters|.{{PermissionSetParameters/state}} is an inappropriate [=permission - state=] for any implementation-defined reason, return a [=invalid argument=] [=error=]. -

    - 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. -

    -
    5. -
  5. Let |settings| be the [=current settings object=]. -
    6. -
  6. Let |targets| be a [=list=] containing all [=environment settings objects=] whose - [=environment settings object/origin=] is the same as the - [=environment settings object/origin=] of |settings|. -
    7. -
  7. Let |tasks| be an empty [=list=]. +
  8. Let |settings| be the [=current settings object=].
    9. +
  9. Let |targets| be a list containing all [=environment settings objects=] + whose [=environment settings object/origin=] is [=same origin=] as + the [=environment settings object/origin=] of |settings|.
    10. +
  10. Let |tasks| be an empty list.
  11. For each [=environment settings object=] |target| in |targets|:
    1. [=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:
        -
      1. Interpret |parameters|.{{PermissionSetParameters/state}} as if it were the - result of an invocation of [=permission state=] for |typedDescriptor| with the +
      2. Interpret |state| as if it were the + result of an invocation of [=permission state=] for |descriptor| with the argument |target| made at this moment.
      2. -
    2. [=list/Append=] |task| to |tasks|. -
      3. +
    3. [=list/Append=] |task| to |tasks|.
    12. -
  12. Wait for all [=tasks=] in |tasks| to have executed. -
    13. -
  13. Return [=success=] with data `null`. -
    14. +
  14. Wait for all tasks in |tasks| to have executed and return.
-
+
+

+ Automated testing with [[WebDriver]] +

+

+ This document defines the following extension commands for the [[WebDriver]] specification. +

+
+

+ Set Permission +

+ + + + + + + + + + + +
+ HTTP Method + + [=extension command URI template|URI Template=] +
+ POST + + /session/{session id}/permissions +

- 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 Set Permission + extension command simulates user modification of a {{PermissionDescriptor}}'s + [=permission state=].

- 
-          {
-            "descriptor": {
-              "name": "midi",
-              "sysex": true
-            },
-            "state": "granted"
-          }
-
- +

+ The remote end steps are: +

+
    +
  1. Let |parameters| be the |parameters| argument, converted to an IDL value of + type {{PermissionSetParameters}}. If this throws an exception, return an [=invalid + argument=] [=error=]. +
    2. +
  2. Let |rootDesc| be |parameters|.{{PermissionSetParameters/descriptor}}. +
    3. +
  3. If |parameters|.{{PermissionSetParameters/state}} is an inappropriate permission + state for any implementation-defined reason, return a [=invalid argument=] [=error=]. +

    + For example, user agents that define the "midi" powerful feature as + "always on" can choose to reject a command to set the [=permission state=] to + {{PermissionState/"denied"}} at this step. +

    +
    4. +
  4. Let |typedDescriptor| be the object |rootDesc| refers to, converted to an IDL + value of |rootDesc|.{{PermissionDescriptor/name}}'s [=powerful + feature/permission descriptor type=]. If this throws an exception, return a [=invalid + argument=] [=error=]. +
    5. +
  5. + [=Set a permission=] with |typedDescriptor| and |parameters|.{{PermissionSetParameters/state}}. +
    6. +
  6. Return success with data `null`. +
    7. +
+ +
+
+
+

+ Automated testing with [[WebDriver-BiDi]] +

+

+ This document defines the following [=extension modules=] for the [[WebDriver-BiDi]] specification. +

+
+

+ The permissions Module +

+

+ The permissions module contains commands for + managing the remote end browser permissions. +

+
+
+ Definition +
+

+ [=remote end definition=] +

+ 
+              PermissionsCommand = (
+                permissions.setPermission
+              )
+
+
+
+
+ Types +
+
+
+ The permissions.PermissionDescriptor Type +
+ 
+                permissions.PermissionDescriptor = {
+                  name: text,
+                }
+
+

+ The `permissions.PermissionDescriptor` type represents a {{PermissionDescriptor}}. +

+
+
+
+ The permissions.PermissionState Type +
+ 
+                permissions.PermissionState = "granted" / "denied" / "prompt"
+
+

+ The `permissions.PermissionState` type represents a {{PermissionState}}. +

+
+
+
+
+ Commands +
+
+
+ The permissions.setPermission Command +
+

+ The Set Permission + [=command=] simulates user modification of a {{PermissionDescriptor}}'s + [=permission state=]. +

+
+
Command Type
+
+ 
+                    permissions.setPermission = (
+                      method: "permissions.setPermission",
+                      params: permissions.SetPermissionParameters
+                    )
+
+                    permissions.SetPermissionParameters = {
+                      descriptor: permissions.PermissionDescriptor,
+                      state: permissions.PermissionState,
+                    }
+
+
+
Result Type
+
+ 
+                    EmptyResult
+
+
+
+
+

+ The [=remote end steps=] with |session| and |command parameters| are: +

+
    +
  1. + Let |descriptor| be the value of the `descriptor` field of + |command parameters|. +
    2. +
  2. + Let |permission name| be the value of the `name` field of + |descriptor| representing {{PermissionDescriptor/name}}. +
    3. +
  3. + Let |state| be the value of the `state` field of |command + parameters|. +
    4. +
  4. + If |state| is an inappropriate [=permission state=] for any + implementation-defined reason, return [=error=] with [=error code=] [=invalid argument=]. +
    5. +
  5. + 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=]. +
    6. +
  6. [=Set a permission=] with |typedDescriptor| and |state|.
    7. +
  7. Return [=success=] with data `null`.
    8. +
+ +
+
+