From 3f6a94ba55c44339069237cbd5d25741fa72ac8a Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 14 Jun 2024 13:58:58 +0200 Subject: [PATCH] Add an Automation section with WebDriver support to the spec Add WebDriver endpoints which allow manipulating virtual pressure sources, which are pressure sources whose behavior and samples are entirelly user-controlled. Also contrary to regular pressure sources, the provided samples (or, in spec parlance, a virtual pressure source's latest sample's data) are already PressureState instances rather than raw telemetry data that will be transformed into an adjusted pressure state. Caveats: - Shared workers are unsupported at the moment (i.e. the WebDriver endpoints only have an effect on Window and DedicaredWorkerGlobalScope globals). Storing virtual pressure source information in a top-level traversable does not play well with shared workers, for which the concept is somewhat irrelevant. We need to think of a different solution in the future if support for shared workers is important. - Once `PressureObserver.observe()` resolves, the same platform collector will be used until `disconnect()` or `unobserve()` are called. In other words, if a PressureObserver instance is active and using a real pressure source, adding a virtual pressure source of the same type will only have an effect on it and other instances in the same global once they all disconnect from the existing pressure source first. In terms of changes to the existing algorithms and concepts: - A top-level traversable has a mapping of source types to virtual pressure sources that is manipulated by the WebDriver endpoints. - When creating a new platform collector, `PressureObserver.observe()` first attempts to use a virtual pressure source when one exists and can be used. - The data collection algorithm distinguishes between the data format used by a virtual pressure source (which already is a PressureState) and by a real pressure source (which needs to be transformed into a PressureState). Co-authored with @kenchris in #265. It was split off as a separate pull request to make it easier to review and understand. Fixes #282. --- index.html | 521 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 503 insertions(+), 18 deletions(-) diff --git a/index.html b/index.html index e41190f..8c616fa 100644 --- a/index.html +++ b/index.html @@ -257,7 +257,8 @@

Sampling and Reporting Rate

+
+

+ Automation +

+

+ The Compute Pressure API poses a challenge to test authors, as fully + exercising interface requires physical hardware devices that respond in + predictable ways. +

+

+ To address this challenge this document defines a [[!WEBDRIVER2]] [=extension + commands=] that allows defining and controlling virtual pressure sources that behave + like real ones and which can have particular properties and whose readings can be + entirely defined by users. +

+

+ Virtual Pressure Source +

+

+ A virtual pressure source is a [=pressure source=] that + simulates the behavior of a real one in controlled ways. It reports + pressure changes to zero or more [=platform collectors=] connected to it. +

+

+ Contrary to a real [=pressure source=], however, it reports [=pressure + state=] values directly instead of [=implementation-defined=] values that + must be processed into [=pressure states=] by a [=platform collector=]. In + other words, a [=virtual pressure source=]'s [=pressure source sample=]'s + [=pressure source sample/data=] is a {{PressureState}}. +

+

+ In addition to the data associated with all [=pressure sources=] (such as + [=pressure source sample=]), each [=virtual pressure source=] has: +

+

+

+ Each [=top-level traversable=] has a virtual pressure source mapping, which is an [=ordered map=] of + [=source types=] to [=virtual pressure source=]. +

+ + +

+ Extension Commands +

+

+ Create virtual pressure source +

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

+ This [=extension command=] creates a new [=virtual pressure source=] of a specified + [=source type=]. Calls to {{PressureObserver/observe()}} from {{PressureObserver}} instances + of the same [=source type=] will cause this [=virtual pressure source=] to be used as their + backing [=pressure source=] until [[[#delete-virtual-pressure-source]]] is run. +

+ + + + + + + + + + + + + + + + + +
+ Properties of the parameters argument used by this algorithm +
+ Parameter name + + Value type + + Required +
+ type + + String + + yes +
+ supported + + Boolean + + no +
+

+ The [=remote end steps=] given |session|, |URL variables| and |parameters| are: +

+
    +
  1. + Let |virtualPressureSourceType| be the result of invoking + get a property "type" from |parameters|. +
    2. +
  2. + If the [=user agent=]'s [=supported source types=] does not + [=list/contain=] |virtualPressureSourceType|, return [=error=] with + [=error code|WebDriver error code=] [=invalid argument=]. +
    3. +
  3. + Let |topLevelTraversable| be the current browsing + context's [=browsing context/top-level traversable=]. +
    4. +
  4. + Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. +
    5. +
  5. + If |topLevelVirtualPressureSourceMapping| contains |virtualPressureSourceType|, return [=error=] with + [=error code|WebDriver error code=] [=invalid argument=]. +
    6. +
  6. + Let |supported| be the result of invoking get a + property with default + with "supported" and true from |parameters|. +
    7. +
  7. + Let |virtualPressureSource| be a new [=virtual pressure source=]. +
    8. +
  8. + Set |virtualPressureSource|'s [=virtual pressure source/can provide + samples=] to |supported|. +
    9. +
  9. + Set |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|] to |virtualPressureSource|. +
    10. +
  10. + Return [=success=] with data null. +
    11. +
+

+ Delete virtual pressure source +

+ + + + + + + + + +
+ HTTP Method + + [=extension command URI Template|URI Template=] +
+ DELETE + + /session/{session id}/pressuresource/{type} +
+

+ This [=extension command=] deletes a given [=virtual pressure source=], meaning that, + if available, data for the given [=source type=] will be delivered the regular way, by non-virtual means. +

+

+ The [=remote end steps=] given |session|, |URL variables| and |parameters| are: +

+
    +
  1. + Let |virtualPressureSourceType| be the value of the |URL variables|["type"]. +
    2. +
  2. + If the [=user agent=]'s [=supported source types=] does not + [=list/contain=] |virtualPressureSourceType|, return [=error=] with + [=error code|WebDriver error code=] [=invalid argument=]. +
    3. +
  3. + Let |topLevelTraversable| be the current browsing + context's [=browsing context/top-level traversable=]. +
    4. +
  4. + Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. +
    5. +
  5. + Let |pressureSource| be |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|]. +
    6. +
  6. + [=set/For each=] |platformCollector| of |pressureSource|'s [=virtual + pressure source/connected platform collectors=]: +
      +
    1. + Set |platformCollector|'s [=platform collector/associated pressure + source=] to null. +
      2. +
    +
    7. +
  7. + [=map/Remove=] |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|]. +
    8. +
  8. + Return [=success=] with data null. +
    9. +
+ +

+ Update virtual pressure source +

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

+ This [=extension command=] allows updating the state of a [=virtual pressure source=] by pushing + a new [=pressure source sample=]. +

+ + + + + + + + + + + + + +
+ Properties of the parameters argument used by this algorithm +
+ Parameter name + + Value type + + Required +
+ sample + + {{PressureState}} + + yes +
+

+ The [=remote end steps=] given |session|, |URL variables| and |parameters| are: +

+
    +
  1. + Let |virtualPressureSourceType| be the value of the |URL variables|["type"]. +
    2. +
  2. + If the [=user agent=]'s [=supported source types=] does not + [=list/contain=] |virtualPressureSourceType|, return [=error=] with + [=error code|WebDriver error code=] [=invalid argument=]. +
    3. +
  3. + Let |topLevelTraversable| be the current browsing + context's [=browsing context/top-level traversable=]. +
    4. +
  4. + Let |topLevelVirtualPressureSourceMapping| be the |topLevelTraversable|'s [=virtual pressure source mapping=]. +
    5. +
  5. + If |topLevelVirtualPressureSourceMapping| does not [=map/contain=] |virtualPressureSource|, + return [=error=] with [=error code|WebDriver error code=] + unsupported operation. +
    6. +
  6. + Let |virtualPressureSource| be |topLevelVirtualPressureSourceMapping|[|virtualPressureSourceType|]. +
    7. +
  7. + Let |sample| be the result of invoking + get a property "sample" from |parameters|. +
    8. +
  8. + If |sample| is not of type {{PressureState}}, return [=error=] with [=error code|WebDriver error code=] [=invalid argument=]. +
    9. +
  9. + Set |virtualPressureSource|'s [=pressure source/latest sample=] to a new + [=pressure source sample=] whose [=pressure source sample/data=] is + |sample| and [=pressure source sample/timestamp=] is the [=unsafe shared + current time=]. +
    10. +
  10. + In an [=implementation-defined=] way, make |virtualPressureSource|'s + [=pressure source/latest sample=] available to |virtualPressureSource|'s + [=virtual pressure source/connected platform collectors=]. +
    11. +
  11. + Return [=success=] with data null. +
    12. +
+