Permissions Automation

Unofficial Proposal Draft,

This version:
https://w3c.github.io/permissions-automation/
Previous Versions:
Feedback:
public-webappsec@w3.org with subject line “[permissions-automation] … message topic …” (archives)
Issue Tracking:
GitHub
Editor:

Abstract

Through extensions to the Web Driver specification, this specification facilitates testing of the Permissions API.

Status of this document

1. Automation

For the purposes of user-agent automation and application testing, this document defines the following extension command for the [WebDriver] specification.

dictionary PermissionSetParameters {
  required PermissionDescriptor descriptor;
  required PermissionState state;
  boolean oneRealm = false;
};

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

  1. Let parameters be the parameters argument, converted to an IDL value of type PermissionSetParameters. If this throws an exception, return a WebDriver error with WebDriver error code invalid argument.
  2. Let rootDesc be parameters.descriptor.
  3. Let typedDescriptor be the object rootDesc refers to, converted to an IDL value of rootDesc.name’s permission descriptor type. If this throws an exception, return a WebDriver error with WebDriver error code invalid argument.
  4. If parameters.state is an inappropriate permission state for any implementation-defined reason, return a WebDriver error with WebDriver error code invalid argument.

    For example, user agents that define the "midi" powerful feature as "always on" may choose to reject command to set the permission state to "denied" at this step.

  5. Let settings be the environment settings object of the current browsing context’s active document.
  6. If settings is a non-secure context and rootDesc.name isn’t allowed in non-secure contexts, return a WebDriver error with WebDriver error code invalid argument.
  7. If parameters.oneRealm is true, let targets be a list whose sole member is settings.
  8. Otherwise, let targets be a list containing all environment settings objects whose origin is the same as the origin of settings.
  9. Let tasks be an empty list.
  10. For each environment settings object target in targets:
    1. Queue a task task on the permission task source of target’s relevant settings object's global object's browsing context to perform the following step:
      1. Interpret parameters.state as if it were the result of an invocation of permission state for typedDescriptor with the argument target made at this moment.
    2. Append task to tasks.
  11. Wait for all tasks in tasks to have executed.
  12. Return success with data null.
To set permission for {name: "midi", sysex: true} of the current browsing context of the session with ID 23 to "granted", the local end would POST to /session/23/permissions with the body:
{
  "descriptor": {
    "name": "midi",
    "sysex": true
  },
  "state": "granted"
}

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[PERMISSIONS]
Mounir Lamouri; Marcos Caceres; Jeffrey Yasskin. Permissions. 20 July 2021. WD. URL: https://www.w3.org/TR/permissions/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[WebDriver]
Simon Stewart; David Burns. WebDriver. 5 June 2018. REC. URL: https://www.w3.org/TR/webdriver1/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

dictionary PermissionSetParameters {
  required PermissionDescriptor descriptor;
  required PermissionState state;
  boolean oneRealm = false;
};