New capability: `injectScript`

Summary: a new capability that inserts a user-specified JavaScript file into each page visited during the session.

Many new web platform features concern systems that cannot be controlled via JavaScript directly. In some cases, this is because the authority is external to the browser (e.g. Generic Sensors, getUserMedia, and Web Bluetooth). In other cases, the browser is the authority, but ceding control to JavaScript would violate fundamental security concerns (e.g. Permissions, Payments, and Web Authentication).

In either case, application developers cannot script the behavior of these APIs. This makes it difficult to test the code they have written on top of them. Browser implementers and spec authors have considered a few solutions to this problem:

• Standardizing JavaScript APIs in the specifications themselves
• Standardizing WebDriver "extension APIs" in the specifications themselves
• Implementing a browser-specific but non-standard JavaScript API (and perhaps building a facade as a unified interface across browsers)

Much of the conversation I have seen about these alternatives has been in the context of conformance testing and the web-platform-tests project. There, it's important to maximize the amount of internal logic that is placed under test. That isn't a consideration for the typical web developer, though, so those solutions may all be overwrought.

In many cases, application developers can (and do) side-step limitations in script-ability by overriding globally-defined APIs with "mock" implementations written in pure JavaScript. This gives them all the control they need to test their code. Because it occurs outside of the standardization process, it also empowers a much larger group of participants and enables more rapid experimentation.

Although all this can be done without WebDriver, this specification may be in a position to assist.

In order for their mock to be used, developers have to replace the true implementation before their application code runs. (Otherwise, their code may create internal references to the true implementation which would not be updated by a subsequent introduction of a mock.) For some, this can be as simple as inserting a <script> tag in a testing environment. Others may not have this level of control. And while code may be structured to support dynamic injection of mocks, the overhead of maintaining this kind of code (and avoiding its abuse in production settings) is non-negligible.

If WebDriver offered a way for developers to run some JavaScript code prior to all other scripts, they would have a standard pattern for solving this problem across all of their projects--one that required no advanced build system (assuming they have a build system). I think this could be provided via a WebDriver capability whose value is the path to a JavaScript file. Developers could maintain their mocks in this file and then use "execute script" to control the behavior of the normally-untestable APIs--simulating sensor readings, payment receipt, and so on.

No repository file or test is named. Start by reading the WebDriver capability and execute script specification entry points, then clarify the injection timing, scope, and path semantics. Done means the proposed capability has an agreed standard definition and corresponding specification coverage.