Introduce WebDriver extension API #369

Honry · 2018-08-16T10:35:34Z

Fixed #363

This spec defines extension commands to the WebDriver spec for controlling mock sensor on the host that the user agent is running on for testing purposes. With these extension commands devices with particular properties can be created and their responses to requests are well defined.

This is the first draft revision, comments are welcome!
/cc @foolip, @kereliuk, @rakuco, @anssiko

Fixed w3c#363 This spec defines extension commands to the WebDriver spec for controlling mock sensor on the host that the user agent is running on for testing purposes. With these extension commands devices with particular properties can be created and their responses to requests are well defined.

foolip · 2018-08-16T19:38:28Z

Hmm, https://github.com/w3c/sensors/blob/master/.pr-preview.json exists, and yet I see no preview on this PR. It worked on #368 so that's weird. @tobie, is the system down?

foolip · 2018-08-16T19:39:03Z

Ah, it's because it's a separate file, webdriver-extension/index.bs. Never mind me.

foolip

I'm not one of the regular reviewers for this repo and my approval won't be green, but LGTM with nits and excitement!

foolip · 2018-08-16T19:55:55Z

webdriver-extension/index.bs

+Group: dap
+ED: https://w3c.github.io/sensors/webdriver-extension
+Editor: Wanming Lin 91067, Intel Corporation, https://intel.com/
+Abstract: This document defines <a>extension commands</a> to the [[WebDriver]] specification for the purposes of testing a user agent’s implementation of Generic Sensor API [[GENERIC-SENSOR]] and its concrete Sensor APIs.


Uber-nit: I believe that if you write [[WebDriver|WebDriver specification]] and [[GENERIC-SENSOR| Generic Sensor API|| here, the result will be a bit more pleasing, without visual angle brackets. (I try to think of [stuff in brackets] as sort of footnotes so that the text should readable if they are removed. It is for the second case but not the first.

Yeah, exactly!

foolip · 2018-08-16T19:57:04Z

webdriver-extension/index.bs

+
+Note: It's up to the user agent to expose what kinds of <a>mock sensor reading</a> to the <a>Sensor</a> objects.
+
+A [=mock sensor=] has an associated <a>latest reading</a> [=ordered map|map=], which holds the latest available [=mock sensor readings=].


Defining the model clearly like this is great!

foolip · 2018-08-16T19:58:01Z

webdriver-extension/index.bs

+<pre class='idl'>
+  dictionary MockSensorConfiguration {
+    required MockSensorType mockSensorType;
+    boolean sensorShouldConnected = true;


Should this be sensorShouldBeConnected? Or maybe just connected given how it's later used? I guess it depends on whether it looks to web content like the sensor was always there, or if it appears and becomes connected in discrete steps.

This is a flag aims to test NotReadableError by simulating sensor connection fails. connected looks good to me.

webdriver-extension/index.bs

foolip · 2018-08-16T20:08:46Z

webdriver-extension/index.bs

+   of type {{MockSensorConfiguration}}. If this throws an exception, return a
+   <a>WebDriver error</a> with <a>WebDriver error code</a> <a>invalid argument</a>.
+2. Let |type| be the |configuration|.{{MockSensorConfiguration/mockSensorType}}, if <a>current browsing context</a>
+   already exists this |type| of [=mock sensor=], return a <a>WebDriver error</a> with <a>WebDriver error code</a>


I think this should read "if the current browsing context already has this type" or similar?

But more importantly, this means that only one sensor of a given type can be created. I assume that's fine, but can you mention it somewhere more prose-y or in a note, so that people who try to use the API understand this quickly?

Good catch! I will mention it somewhere.

foolip · 2018-08-16T20:11:35Z

webdriver-extension/index.bs

+  1. Set the [=mock sensor type|mock sensor's type=] to |type|.
+  2. Let |connected| be the |configuration|.{{MockSensorConfiguration/sensorShouldConnected}},
+     force the result of invoking <a>connect to sensor</a> with associated <a>Sensor</a> instance as argument to |connected|.
+  3. If |configuration|.{{MockSensorConfiguration/maxSamplingFrequency}} is [=present=], then


Punctu-nit: Colon after then when it's followed by steps or a new sentence.

Thanks, fixed.

foolip · 2018-08-16T20:12:44Z

webdriver-extension/index.bs

+4. Return <a>success</a> with data `null`.
+
+<div class="example">
+  To create an "ambient-light" mock sensor of <a>current browsing context</a> of the <a>session</a> with ID 23,


Sweet, examples! Maybe this would be a good place to comment about what happens if one tries to do it twice.

Agree, that's a good place!

foolip · 2018-08-16T20:13:21Z

webdriver-extension/index.bs

+  </tbody>
+</table>
+
+The <dfn>Get mock sensor</dfn> <a>extension command</a> simulates user


Repeat-nit: get

Thanks, fixed.

foolip · 2018-08-16T20:15:11Z

webdriver-extension/index.bs

+
+The <a>remote end steps</a> are:
+1. Let |type| be a <a>url variable</a>.
+2. If {{MockSensorType}} [=set/contains|does not contain=] |type|, return a <a>WebDriver error</a> with


I fear that https://infra.spec.whatwg.org/#list-contain isn't the right operation for checking if a string is an enum member. Maybe something like trying to convert the string to an IDL value, or check if WebDriver itself does this somewhere. I'd ask @AutomatedTester if in doubt.

Hmm, I am not quite sure either, but using "convert the string to an IDL value" would be more appropriate.

- Fix some editorial issues - Use "connected" to replace "sensorShouldConnected" - Comment what would happen if create mock sensor twice - Improve identification of MockSensorType type

Honry · 2018-08-17T07:59:53Z

@foolip, thanks for your review! Do you know how to add a preview for such index.bs in sub folder?

tobie · 2018-08-17T08:03:15Z

Do you know how to add a preview for such index.bs in sub folder?

Unfortunately, pr-preview doesn't support this. I'm happy to take a pull request that would enable it, or discuss contracting offers to implement it myself.

tobie · 2018-08-17T08:09:47Z

This is amazing, btw.

Honry · 2018-08-17T08:10:13Z

@tobie, thank you!

tobie · 2018-08-17T08:11:27Z

…and not only for testing the sensor specs themselves, but this is also going to be extremely helpful for all sorts of app-level testing by developers. Have you gathered input from devs yet?

Honry · 2018-08-17T08:33:35Z

We have some discussions in #363, but only involved devs from sensors spec(e.g. @alexshalamov, @rakuco), and also @foolip, @kereliuk, who are helping review it

Inputs from devs outside of sensor specs are really helpful, @tobie, do you know who else we can invite?

foolip · 2018-08-17T09:17:30Z

I would file a request for feedback issue at https://github.com/w3c/webdriver/issues/new, point to here, and then close it again.

tobie · 2018-08-17T09:52:17Z

I was thinking about:

DevRel folks, e.g. @kenchris.
Companies offering Selenium integration solution, e.g. Saucelab.
Web developers at large, e.g. via Twitter and other channels (maybe @rwaldron wants to mention this.)

tobie · 2018-08-17T09:57:28Z

I would recommend moving this spec to its own repository (if only to get pr-preview to kick in), and to start by writing an explainer doc, which will make it easier for Web developers to understand what this is about and provide input.

foolip · 2018-08-17T10:10:03Z

I would rather advise against treating this as a separate thing. The world I'd like to get to is where test automation is simply treated like a part of the spec itself, woven into it just like IDL interfaces, security considerations, etc. https://w3c.github.io/permissions/#automation is an example of this. In this case it's pretty big and a separate document is fine, but the further separated from the main specification, the more likely it is to be overlooked when future spec changes are made.

tobie · 2018-08-17T10:16:52Z

That's an interesting point. I guess PR preview needs an update, then. What about the explainer, though?

foolip · 2018-08-17T10:33:10Z

That would be nice. Looks like https://github.com/w3c/sensors doesn't have one, but putting it in the same explainer would align with my scheming :D

tobie · 2018-08-17T11:31:05Z

Heh. I take the blame for the initial absence of explainer. I wasn't bought in to the idea when I started spec'ing the Generic Sensor API—preferring to make the spec more accessible to developers instead. I've been convinced of the opposite since.

Honry · 2018-08-20T05:47:17Z

start by writing an explainer doc, which will make it easier for Web developers to understand what this is about and provide input.

Agree. I'll write an explainer doc.

jugglinmike

Exciting work here, @Honry! I have a few high-level comments that don't really work as in-line feedback.

Sampling frequency By allowing users to set the minSamplingFrequency and maxSamplingFrequency, we are giving them a way to influence the sampling frequency. These constraints are useful for platform sensors which varying physical limitations. There are no such constraints in this case, though. What do you think about exposing the "sampling frequency" directly? That would give users more control over the behavior of their mock devices.

Readings Speaking as a web developer, think this API may not be powerful enough to thoroughly test my applications. Unless I am mistaken, the API requires a POST request for each new sensor reading I want to simulate. In many cases, I may not be able (or willing) to issue HTTP requests at an acceptable rate, especially if the remote end is running over the Internet (maybe via a third party like Sauce Labs).

Instead of sending individual readings in a series, what if I could specify a JavaScript function capable of creating those readings? The implementation could call this at the device's sampling frequency, and if it provided a timestamp, I would be able to derive an expected value in a stateless way. Alternatively, we could accept an ES2015 generator function. A generator could yield readings and receive timestamps from the result (or I could maintain the timestamp myself using the performance timing API). In either case, we could use WebDriver's "execute script" command as a guide.

"Interception" When readers learn that some parts of the spec may override other parts, they may lose confidence in the algorithms themselves. "Yes, I can see what the steps say, but how do I know that this algorithm is even running right now?" This gets at the ongoing conversation about the appropriate location of this text. If it uses techniques like "intercept," maintaining it as a separate document will exacerbate the issue. gh-363 contains some feedback from @anssiko about the motivation: "to not intervene with the Generic Sensor API spec itself that is now at CR." I don't have more context than that, but naively, I think intervention is unavoidable for such a feature as significant as automation capabilities.

We could partially address it with non-normative text in the definition of "connect to sensor" ("Note: the result of this algorithm may be intercepted in automated scenarios."), but that would still be treating it as somehow less relevant than the mainline algorithm. Even better would be to extend the algorithm itself, coarsely "1. If MockSensorConfiguration/connected is set, return true."

jugglinmike · 2018-08-20T16:11:40Z

webdriver-extension/index.bs

+A [=mock sensor=] reports corresponding <dfn id="mock-sensor-reading">mock <a>sensor reading</a></dfn>, which is a source of
+mocking information about the environment, to the <a>Sensor</a> objects.
+
+Note: It's up to the user agent to expose what kinds of <a>mock sensor reading</a> to the <a>Sensor</a> objects.


"[are available] to the Sensor objects"

Hmm, actually it is "expose .... reading to the Sensor objects".

User agent can determine exposing what kinds of mock sensor reading. e.g. in Chromium mock sensor, it always expose 0 as reading values, except the increasing timestamp. And this spec is allowed to set customized reading values, which is introduced in "Update mock sensor reading" section.

I think I understand. It sounds like the UA doesn't get to choose the kind of
reading, but rather the reading itself (or more precisely, its value). Is that
right? If so, we should remove the phrase "what kinds of":

Note: It's up to the user agent to expose mock sensor reading[s] to the
Sensor objects.

Is that accurate? It's a little vague of me, though--of course the UA has to
expose readings! It might be more precise/helpful to say something like:

Note: The user agent must select the mock sensor readings that are initially
exposed to the Sensor objects.

Yep, you are right. How about use "provide"(or maybe "set") instead of "select"?

Note: The user agent must provide the mock sensor readings that are initially
exposed to the Sensor objects.

Works for me!

jugglinmike · 2018-08-20T16:12:31Z

webdriver-extension/index.bs

+
+A [=mock sensor=] has an associated <a>latest reading</a> [=ordered map|map=], which holds the latest available [=mock sensor readings=].
+
+A [=mock sensor=] has an associated <a>requested sampling frequency</a> which is initial set to null.


"initial[ly] set to null."

Thanks, will fix it.

jugglinmike · 2018-08-20T16:14:14Z

webdriver-extension/index.bs

+:: A {{MockSensorType}} that is used to set <a>mock sensor type</a>.
+
+: {{MockSensorConfiguration/connected}} member
+:: A boolean. When set to false the user agent should intecept the result of invoking <a>connect to sensor</a>


"inte[r]cept the result"

"should" -> "must"

Thanks, will fix it.

jugglinmike · 2018-08-20T16:35:35Z

webdriver-extension/index.bs

+
+: {{MockSensorConfiguration/connected}} member
+:: A boolean. When set to false the user agent should intecept the result of invoking <a>connect to sensor</a>
+   with associated <a>Sensor</a> instance as argument to false, otherwise true.


I haven't seen "intercept the result" before, but I'm pretty green when it
comes to spec infra. If this is a well-defined concept, a reference would be
helpful. If it's new, on the other hand, then we may be able to make it more
clear.

If I'm reading it correctly, then the action that is being "intercepted" is
"invoking connect to sensor with associated Sensor instance as argument." In
that case, the generic operation would read "intercept the result [...] to
false, otherwise true." It seems likely that "intercept the result to false"
means "return false," but if so, the wording could be improved.

Then again, the concept of "interception" is not really ideal. I'll elaborate
in a separate comment.

jugglinmike · 2018-08-20T16:39:02Z

webdriver-extension/index.bs

+Each <a>mock sensor type</a> has the following <a>mock sensor reading set</a>:
+
+: A <dfn export>Mock Sensor Reading Set</dfn>
+:: {{MockSensorReadingSet}} dictionary represents a set of user specific <a>mock sensor reading</a> used for


"user specific" -> "user-specified"

Thanks, will fix it.

jugglinmike · 2018-08-20T16:39:19Z

webdriver-extension/index.bs

+
+: A <dfn export>Mock Sensor Reading Set</dfn>
+:: {{MockSensorReadingSet}} dictionary represents a set of user specific <a>mock sensor reading</a> used for
+   [[#update-mock-sensor-reading-command|updating mock sensor reading]]. It must contains all members of a


"contains" -> "contain"

webdriver-extension/index.bs

jugglinmike · 2018-08-20T17:23:24Z

webdriver-extension/index.bs

+Each enumeration value in the {{MockSensorType}} enum identifies a <a>mock sensor type</a>.
+Each <a>mock sensor type</a> has the following <a>mock sensor reading set</a>:
+
+: A <dfn export>Mock Sensor Reading Set</dfn>


These values are not sets but dictionaries. Do you think shortening the name to "MockSensorReading" would be appropriate?

Indeed, "MockSensorReading" LGTM. But if we remove the "Set" suffix, the "GeolocationReadingSet" would be quite similar to GeolocationSesnorReading.

How about "MockSensorReadingParamters" or "MockSensorReadingSetParamters"(maybe "MockSensorReadingSetParams" in short)? I was thinking it looks too long.

I finally choose the ”MockSensorReadingSetParams“. A sensor reading contains timestamps, but user don't need to update the timestamps.

jugglinmike · 2018-08-20T18:35:47Z

webdriver-extension/index.bs

+## Handling errors ## {#extension-handling-errors}
+
+This section extends the <a>Handling Errors</a> and defines extended <a>WebDriver error codes</a>
+specific for [=mock sensor=] in following table.


WebDriver attempts to fully define the way extension commands are defined, but it does not support introducing new errors. The functionality has already been requested; we should see what we can do about moving that forward as part of this work.

Yeah, that's a problem! I read the feature request before but forget to expose it in previous discussion. :P

Honry · 2018-08-21T09:47:26Z

@jugglinmike, wow! Really appreciate for such elaborate comments!

Sampling frequency By allowing users to set the minSamplingFrequency and maxSamplingFrequency, we are giving them a way to influence the sampling frequency. These constraints are useful for platform sensors which varying physical limitations. There are no such constraints in this case, though. What do you think about exposing the "sampling frequency" directly? That would give users more control over the behavior of their mock devices.

I am fine on exposing the "sampling frequency" directly, but Chromium Layout tests have tests for minSamplingFrequency and maxSamplingFrequency, @rakuco, @alexshalamov, WDYT?

Readings Speaking as a web developer, think this API may not be powerful enough to thoroughly test my applications. Unless I am mistaken, the API requires a POST request for each new sensor reading I want to simulate. In many cases, I may not be able (or willing) to issue HTTP requests at an acceptable rate, especially if the remote end is running over the Internet (maybe via a third party like Sauce Labs).

I may made a mistake here, my thought was making the new sensor reading always be the value from invoking "Update mock sensor reading" command, thus the mock sensor will always expose the same reading, which is what chromium mock sensor implemented.

So we should "set the new mock sensor reading to .." instead of "invoking update latest reading" and define what is new mock sensor reading. Does it make sense to you?

"Interception" We could partially address it with non-normative text in the definition of "connect to sensor" ("Note: the result of this algorithm may be intercepted in automated scenarios."), but that would still be treating it as somehow less relevant than the mainline algorithm. Even better would be to extend the algorithm itself, coarsely "1. If MockSensorConfiguration/connected is set, return true."

I was also with concern when I used "Interceptor". I don't have a better idea, @rakuco, @anssiko, do you have any input?

jugglinmike · 2018-08-21T17:41:00Z

@jugglinmike, wow! Really appreciate for such elaborate comments!

My pleasure :)

So we should "set the new mock sensor reading to .." instead of "invoking
update latest reading" and define what is new mock sensor reading. Does it
make sense to you?

I wasn't aware of Chromium's implementation; thanks for the background! It sounds
like what I'm proposing is fundamentally more powerful than that, though.

An application developer might write some code to respond to a rapid increase
in brightness. To test their application logic using this new WebDriver API,
they'd need to simulate the increase via a series of POST requests:

POST /session/c0ffee/sensor/ambient-light
{"illuminance": 0}
POST /session/c0ffee/sensor/ambient-light
{"illuminance": 0.2}
POST /session/c0ffee/sensor/ambient-light
{"illuminance": 0.4}
POST /session/c0ffee/sensor/ambient-light
{"illuminance": 0.6}
POST /session/c0ffee/sensor/ambient-light
{"illuminance": 0.8}
POST /session/c0ffee/sensor/ambient-light
{"illuminance": 1}

However, they won't have any control over when those values get applied.
Depending on network effects, this could be not very rapid at all (and not very
smooth as a result). It will also get more cumbersome for more expressive
sensors (e.g. gyroscope) and for more complex readings (e.g. a "twist"
movement). And since all WebDriver commands execute in series, developers won't
be able to interact with the browser while this is happening.

If instead, the automation API allowed developers to specify a function, they
could express an entire series of sensor readings that was arbitrarily complex
and continuous, and they could do it with a single POST request.

Here's how it might look with a "classic" function body that received the time
offset as its first argument:

POST /session/c0ffee/sensor/ambient-light
{
  "body": "const t = arguments[0]; return {illuminance: Math.min(t / 1000, 1)};"
}

And here's a fancier version using an ES2015 generator function that tracks the
time with its own internal state:

POST /session/c0ffee/sensor/ambient-light
{
  "body": "const start = performance.now(); while (true) { const t = performance.now() - start; yield {illuminance: Math.min(t / 1000, 1)}; }"
}

The latter is more verbose for this example, but the ability to maintain state
could make it much easier to script complex sets of readings.

Honry · 2018-08-22T06:04:30Z

@jugglinmike, thanks again! That's really a good proposal for multiple HTTP requests!

Consider the single HTTP request is the most common scenario and more acceptable. (People might be confuse to use javascript function to send a single request)
How about keep single set of readings as current solution, and extend this section by using WebDriver's "execute script" command to script complex sets of readings?

@rakuco, from the perspective of implementer of mock sensor, do you have any input?

anssiko · 2018-08-22T11:04:07Z

Re intercept, the group can definitely consider rolling this extension API into the Generic Sensor API spec if that makes it easier for implementers to digest. Our charter is indifferent regarding how we organize the spec text. The intent was to avoid mixing "stable" and "experimental" prose together to allow the Generic Sensor API advance beyond CR.

Alternatively, see if adding extension points (new steps) to the Generic Sensor API algorithms and cross-linking to this extension spec would be a workable solution.

jugglinmike · 2018-08-22T19:16:05Z

Consider the single HTTP request is the most common scenario and more
acceptable. (People might be confuse to use javascript function to send a
single request)

I'm reluctant to make design decisions based on the most common scenario of
today because we only have the experience of Chromium implementers to draw
from. Web developers will have distinct needs (other implementers may, too),
and they are a sizable audience for this API. All the more reason to get more
web devs involved!

How about keep single set of readings as current solution, and extend this
section by using WebDriver's "execute script" command to script complex sets
of readings?

That could be a nice simplification, but I don't think the current text
supports it. There doesn't seem to be an JavaScript API to control this, so
the code that developers provide via "Execute Script" doesn't have an interface
to specify mock values.

We could define such a JavaScript API, but that might not be necessary.
Developers may stub out the JavaScript constructor of the device they wish to
mock. Their stub constructor could generate instances which emitted events in
whatever sequence they liked. This just requires injecting code prior to the
evaluation of their application. For some configurations, that could be a
little cumbersome but not impossible. I've filed an issue against WebDriver to
discuss making this easier.

If that is a tenable solution, then maybe web developers aren't an audience for
this feature, after all! What do you think?

Honry · 2018-08-23T07:08:05Z

@jugglinmike, I am a fan of this solution! I'd recommend moving this feature request to level-2 and keep current solution at present since it still depends on WebDriver support. I just create a new issue to track this feature request and let's move to that thread.

JohnChen0 · 2018-11-19T18:42:56Z

webdriver-extension/index.bs

+The <dfn>create mock sensor</dfn> <a>extension command</a> simulates user
+creation of a [=mock sensor=].
+
+The <a>remote end steps</a> are:


Sounds like all the extension commands only affect the current browsing context, not the entire session? For such commands, there should be a step "If the current top-level browsing context is no longer open, return error with error code no such window" near the beginning of the remote end steps. It may also worth considering adding "Handle any user prompts and return its value if it is an error."

@JohnChen0, thanks for catching this! Seems Permission API and Reporting API have similar issue. Are these two steps both necessary for them? Could you provide some guideline on which one I should add and when?

Any WebDriver command that targets a specific top-level browsing context (i.e., a tab or a window) should have a step to check if that browsing context is still open. A WebDriver session has a current browsing context. If the tab or window associated with the current browsing context is closed, then the WebDriver implementation can't carry out the command, and should return an error. The implementation doesn't automatically switch to a different browsing context -- it must be changed explicitly by Switch To Window command. Even if the step is missing from the spec, the implementation would likely be forced to check for this error any way, as there is likely no good way to carry out the command with an invalid current browsing context.

Most commands should also handle user prompts, unless there is some specific reason not to do so. When a prompt is shown, browser functionality is severely limited (e.g., JavaScript code can't be run), and may make it difficult to execute the command.

@JohnChen0, thanks for your clarification! It does help for me.
We should check if the current browsing context is still open rather the current top-level browsing context, right?

If the command primarily affects the current frame (as selected by WebDriver Switch To Frame command), then we should check if the current browsing context is still open. If it primarily affects the current tab/window, then we should check current top-level browsing context.

@JohnChen0, thanks again. I will fix it base on @rakuco's proof-reading.

- Remove trailing `\` in WebDriver endpoint URL - s/argument/parameter - Add two more steps to check if browsing context is still open and handle user prompts

Honry · 2018-11-23T04:19:14Z

@JohnChen0, many thanks for your comments, I've addressed it in new commit, could you PTAL?

JohnChen0 · 2018-11-25T03:17:37Z

LGTM. Thanks!

foolip · 2018-11-26T10:20:16Z

Yay! @Honry, is there anyone else who needs to review this before it's merged?

@LukeZielinski, this PR is a good example of a WebDriver extension of the more difficult nature, might be good to read it over.

rakuco · 2018-11-26T10:45:15Z

I think we're finally good to go :) I guess either @reillyeon or @anssiko needs to merge the PR after doing a final pass over it.

anssiko · 2018-11-26T16:44:55Z

webdriver-extension/explainer.md

+## References & acknowledgements
+
+ - Discussion on public-test-infra mailing list: [UserAgent-specific files in Web Platform Tests](https://www.w3.org/Search/Mail/Public/search?keywords=&hdr-1-name=subject&hdr-1-query=%22UserAgent-specific+files+in+Web+Platform+Tests%22&index-grp=Public_FULL&index-type=g&type-index=)
+ - [Generic Sesnor API](https://w3c.github.io/sensors/#sensor)


Minor nit, typo: s/Sesnor/Sensor/

anssiko · 2018-11-26T16:53:51Z

Congrats and huge thanks @Honry for leading and editing WebDriver Extension API for Generic Sensor spec, as well as to contributors @rakuco @jugglinmike @foolip @JohnChen0, others for reviews, feedback and comments.

I feel good merging this PR. It exceeds the expectations for an initial PR. Any further edits, typo fixes can go in subsequent PRs.

Honry · 2018-11-27T01:37:27Z

It's my pleasure! Thanks everyone!

christian-bromann · 2021-01-05T17:04:21Z

@Honry thanks for adding these endpoints to the WebDriver spec. Did they get up being implemented in any driver?

…ands The previous version from w3c#369 and w3c#377 was never implemented by any engines, and the language it used made it hard to actually implement and use in tests (such as those already present in web-platform-tests). For example: - Mock sensors acted like a mix of device sensors and platform sensors, and the distinction was not entirely clear. - Mock sensors had a separate readings map that never really integrated with the "latest reading" concept used in the abstract operations. - The language in the "Create mock sensor" extension command did not make it clear if it was attempting to create Sensor objects or hand-wavingly change existing Sensor objects' associated platform sensor. - Implementing the custom WebDriver error codes specified here was not trivial and did not bring much extra benefit (other specifications refrain from doing it as well). - Calling "convert to an IDL value" to convert JSON Objects to a platform version is not always trivial to implement since it actually requires a lot of extra WebIDL processing steps that are not really needed here. The new version uses more precise language in the algorithms and properly integrates into the existing abstract operations. It has also been verified to work with Chromium, ChromeDriver and the required changes to web-platform-tests. "Mock sensors" are now called "virtual sensors" to follow the same terminology adopted by the WebAuthn spec. Conceptually, they are now defined as device sensors and therefore always exist at a layer below a platform sensor. This clears up ambiguities and delimits what is expected of platform sensors and what can actually be influenced by a virtual sensor. Additionally, the same virtual sensors are used by all navigables that have the same top-level traversable. In other words, all iframes under the same main frame, regardless of their origin, share the same virtual sensors. Not only does this match the behavior of real, hardware-based sensors more closely, but it also helps with a limitation in web-platform-tests' testdriver.js that only allows WebDriver communication to go through the page that creates the test harness.

…ands The previous version from w3c#369 and w3c#377 was never implemented by any engines, and the language it used made it hard to actually implement and use in tests (such as those already present in web-platform-tests). For example: - Mock sensors acted like a mix of device sensors and platform sensors, and the distinction was not entirely clear. - Mock sensors had a separate readings map that never really integrated with the "latest reading" concept used in the abstract operations. - The language in the "Create mock sensor" extension command did not make it clear if it was attempting to create Sensor objects or hand-wavingly change existing Sensor objects' associated platform sensor. - Implementing the custom WebDriver error codes specified here was not trivial and did not bring much extra benefit (other specifications refrain from doing it as well). - Calling "convert to an IDL value" to convert JSON Objects to a platform version is not always trivial to implement since it actually requires a lot of extra WebIDL processing steps that are not really needed here. The new version uses more precise language in the algorithms and properly integrates into the existing abstract operations. It has also been verified to work with Chromium, ChromeDriver and the required changes to web-platform-tests. "Mock sensors" are now called "virtual sensors" to follow the same terminology adopted by the WebAuthn spec. Conceptually, they are now defined as device sensors and therefore always exist at a layer below a platform sensor. This clears up ambiguities and delimits what is expected of platform sensors and what can actually be influenced by a virtual sensor. Some auxiliary concepts also had to be defined, both of which are expected to be set by extension specifications: - "Virtual sensor metadata" is a struct with a sensor type and an algorithm to parse the readings sent to the "update virtual sensor reading" extension command. - "Per-type virtual sensor metadata" is a mapping of strings to virtual sensor metadata instances. This allows us to get rid of MockSensorType, as the keys are then used to identify a given sensor type in the WebDriver extension commands and each specification defines one or more keys. The same virtual sensors are used by all navigables that have the same top-level traversable. In other words, all iframes under the same main frame, regardless of their origin, share the same virtual sensors. Not only does this match the behavior of real, hardware-based sensors more closely, but it also helps with a limitation in web-platform-tests' testdriver.js that only allows WebDriver communication to go through the page that creates the test harness.

…ands (#470) The previous version from #369 and #377 was never implemented by any engines, and the language it used made it hard to actually implement and use in tests (such as those already present in web-platform-tests). For example: - Mock sensors acted like a mix of device sensors and platform sensors, and the distinction was not entirely clear. - Mock sensors had a separate readings map that never really integrated with the "latest reading" concept used in the abstract operations. - The language in the "Create mock sensor" extension command did not make it clear if it was attempting to create Sensor objects or hand-wavingly change existing Sensor objects' associated platform sensor. - Implementing the custom WebDriver error codes specified here was not trivial and did not bring much extra benefit (other specifications refrain from doing it as well). - Calling "convert to an IDL value" to convert JSON Objects to a platform version is not always trivial to implement since it actually requires a lot of extra WebIDL processing steps that are not really needed here. The new version uses more precise language in the algorithms and properly integrates into the existing abstract operations. It has also been verified to work with Chromium, ChromeDriver and the required changes to web-platform-tests. "Mock sensors" are now called "virtual sensors" to follow the same terminology adopted by the WebAuthn spec. Conceptually, they are now defined as device sensors and therefore always exist at a layer below a platform sensor. This clears up ambiguities and delimits what is expected of platform sensors and what can actually be influenced by a virtual sensor. Some auxiliary concepts also had to be defined, both of which are expected to be set by extension specifications: - "Virtual sensor metadata" is a struct with a sensor type and an algorithm to parse the readings sent to the "update virtual sensor reading" extension command. - "Per-type virtual sensor metadata" is a mapping of strings to virtual sensor metadata instances. This allows us to get rid of MockSensorType, as the keys are then used to identify a given sensor type in the WebDriver extension commands and each specification defines one or more keys. The same virtual sensors are used by all navigables that have the same top-level traversable. In other words, all iframes under the same main frame, regardless of their origin, share the same virtual sensors. Not only does this match the behavior of real, hardware-based sensors more closely, but it also helps with a limitation in web-platform-tests' testdriver.js that only allows WebDriver communication to go through the page that creates the test harness. Co-authored-by: Reilly Grant <reillyeon@users.noreply.github.com>

foolip approved these changes Aug 16, 2018

View reviewed changes

A couple of optimizations

b2d1bca

- Fix some editorial issues - Use "connected" to replace "sensorShouldConnected" - Comment what would happen if create mock sensor twice - Improve identification of MockSensorType type

Honry force-pushed the webdriver-extension branch from 46a134b to b2d1bca Compare August 17, 2018 07:59

jugglinmike mentioned this pull request Aug 20, 2018

Support protocol extension of errors w3c/webdriver#1151

Open

jugglinmike reviewed Aug 20, 2018

View reviewed changes

Fix several typo issues

5bdd8dd

Honry mentioned this pull request Aug 23, 2018

Support scripting complex sets of mock sensor readings #371

Open

JohnChen0 reviewed Nov 19, 2018

View reviewed changes

Raphael Kubo da Costa and others added 2 commits November 23, 2018 09:48

WebDriver Extension API: Do some proof-reading (#2)

67a5046

Address @JohnChen0's comments

246e17b

- Remove trailing `\` in WebDriver endpoint URL - s/argument/parameter - Add two more steps to check if browsing context is still open and handle user prompts

anssiko reviewed Nov 26, 2018

View reviewed changes

anssiko approved these changes Nov 26, 2018

View reviewed changes

anssiko merged commit 8ca30a5 into w3c:master Nov 26, 2018

Honry deleted the webdriver-extension branch November 27, 2018 01:37

Honry mentioned this pull request Nov 27, 2018

Automation: Need two more steps to handle closed browsing context and user prompts w3c/reporting#137

Closed

anssiko mentioned this pull request Jan 17, 2019

Integrated WebDriver Extension API into to Generic Sensor spec #377

Merged

stephenmcgruer mentioned this pull request Nov 3, 2020

RFC: Add TestDriver support for the "Set Timezone" WebDriver extension command web-platform-tests/rfcs#66

Closed

christian-bromann mentioned this pull request Jan 5, 2021

Add new WebDriver extensions webdriverio/webdriverio#6289

Merged

8 tasks

Honry mentioned this pull request Feb 4, 2022

Automation: Need two more steps to handle closed browsing context and user prompts w3c/permissions#347

Closed

rakuco mentioned this pull request Aug 11, 2023

Rewrite the Automation section and redefine the spec's extension commands #470

Merged


		Note: It's up to the user agent to expose what kinds of <a>mock sensor reading</a> to the <a>Sensor</a> objects.

		A [=mock sensor=] has an associated <a>latest reading</a> [=ordered map\|map=], which holds the latest available [=mock sensor readings=].


		A [=mock sensor=] has an associated <a>latest reading</a> [=ordered map\|map=], which holds the latest available [=mock sensor readings=].

		A [=mock sensor=] has an associated <a>requested sampling frequency</a> which is initial set to null.

Introduce WebDriver extension API #369

Introduce WebDriver extension API #369

Conversation

Honry commented Aug 16, 2018

foolip commented Aug 16, 2018

foolip commented Aug 16, 2018

foolip left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Honry Aug 17, 2018 • edited Loading

Choose a reason for hiding this comment

Honry commented Aug 17, 2018

tobie commented Aug 17, 2018

tobie commented Aug 17, 2018

Honry commented Aug 17, 2018

tobie commented Aug 17, 2018

Honry commented Aug 17, 2018 • edited Loading

foolip commented Aug 17, 2018

tobie commented Aug 17, 2018

tobie commented Aug 17, 2018

foolip commented Aug 17, 2018

tobie commented Aug 17, 2018

foolip commented Aug 17, 2018

tobie commented Aug 17, 2018

Honry commented Aug 20, 2018

jugglinmike left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Honry commented Aug 21, 2018

jugglinmike commented Aug 21, 2018

Honry commented Aug 22, 2018

anssiko commented Aug 22, 2018

jugglinmike commented Aug 22, 2018

Honry commented Aug 23, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Honry commented Nov 23, 2018

JohnChen0 commented Nov 25, 2018

foolip commented Nov 26, 2018

rakuco commented Nov 26, 2018

Choose a reason for hiding this comment

anssiko commented Nov 26, 2018

Honry commented Nov 27, 2018

christian-bromann commented Jan 5, 2021 • edited Loading

Honry Aug 17, 2018 •

edited

Loading

Honry commented Aug 17, 2018 •

edited

Loading

christian-bromann commented Jan 5, 2021 •

edited

Loading