Introduce the introducing input automation stubs

[NavidZ]

@foolip @jgraham @RByers
The documentation of the API is written here:
https://navidz.github.io/web-input-automation

This API will be used by the manual web platform
tests to inject user input to the test.

closes #250

---

This change is 

[NavidZ]

Friendly ping.
Can we land this PR if there are no objections?

[jgraham]

The problem here is that this introduces a function that implementors have to implement with totally undefined semantics.

The approach that I proposed taking was the opposite; use the WebDriver specification to define the sematics, provide a default implementation based on WebDriver itself, and allow vendors to override if they have a vendor-specific alternative that can provide the same semantics.

[NavidZ]

WebDriver spec already specified the pointer action APIs but they are not implemented in webdriver js. But WebDriverJs hasn't implemented that yet as far as I know. So assuming we want to just forward parameters to the wpt server and pass them to the webdriver we need to come up with the js API ourselves in wpt tests. Right? So this is what this PR tries to do.

[jgraham]

I quite stronly feel that adding an empty (i.e. broken) default implementation is not a sufficient approach here. I think we have to do the right thing and ensure that what we ship works by default, and can be enhanced by specific implementations where necessary.

[NavidZ]

But even if we add the webdriver and the APIs to the webdriverjs without any driver implementing the pointer actions it will be still broken. Wouldn't it be? As far as I know ChromeDriver is not near implementing this. How about GeckoDriver? At the end we will have at most one driver and the rest will catching up with implementing the pointer action APIs. So it will be still broken on lots of browsers at that time. I believe the reasoning applies here too.

How about this? Would you feel better if I add the default implementation (for Chrome only here) and check whether the testing API is active in the current instance of chrome and if yes then use it. If not just don't do anything. Then similar to the solution above we need to ask other vendors to do the same if they like or just rely on that if not part. Later we can add the if not part and send the command to the webdriver.

[annevk]

@NavidZ but if it's standardized it will be clear to browsers how to get it unstuck. If it's just a "do whatever" function call they have to implement themselves it's not clear how to make things work.

[NavidZ]

I remember @jgraham saying there are not enough interests in standardizing a testing only API. However, I have written up this proposal for the format and the parameters of the API that I have here. I was hoping we can also iterate on the proposed API as well as the implementation with different vendors to get a better insight on what we need in different test situations.

[annevk]

@AutomatedTester can you comment on that perhaps? I'd think at Mozilla at least we'd be very interested in having APIs in WebDriver that enable more automated tests.

[NavidZ]

I believe WebDriverJs hasn't exposed any pointer action API yet. I really like to extend this API and have something similar to this in webdriver js for pointer actions so that one can easily pass the parameters between this API (if any browser exposes it internally to a page) and the web driver if needs be similar to the architecture we had in mind for wpt. So that one can get the performance benefit when they use the internal browser API in the page and if they want the isolation of the webdriver they can easily switch just by forwarding the parameters. That is mainly why everything is summarized in the list of parameters. There can always be client side builder libraries for that json anyway.
I believe it would be much better if we have an API documented and having WebDriver JS an implementation of it (or if any browser wants to expose it directly) rather than WebDriver JS being the only testing API exposed.

[NavidZ]

Any updates on this? @jgraham were you okay with the suggestion regarding the default implementation?

[jgraham]

I believe that @gsnedders is likely to be working on this in the near future. I am still reluctant to merge a pure stub without any cross-browser implementation, because I think it's very unlikely that tests written against a single browser's internal APIs will generalise to work in multiple browsers later.

[jgraham]

c.f. web-platform-tests/wpt#2161