[testdriver] Add an execute_script function to testdriver.

This provides a direct way to execute script in another browsing context.

Author: jgraham

rfcs/execute_script.md

@@ -0,0 +1,69 @@
+# RFC 89: `testdriver` Add an `execute_script` method.
+
+## Summary
+
+Add an `execute_script` method to testdriver that takes the source
+text of the script, an async argument, and the context id to execute
+it it. This follows WebDriver semantics, and the returned promise is
+resolved once the script has a result.
+
+## Details
+
+Sometimes a test window wants to check the status of something in a
+remote window. It's possible to do this in a number of ways, for
+example by posting messages from the remote window to the test
+window. However in cross-origin cases messge passing on the js side
+can be difficult or impossible. In addition when tests are defined in
+the test window, it's useful to avoid putting complex logic in other
+browsing contexts because these won't have the same error handling
+properties as the test window.
+
+A simple way to solve these problems is to provide a mechansim to
+execute script in a different context. This isn't possible using
+content APIs alone, but is possible in WebDriver, and we can reuse
+that to define a `execute_script` function that works across contexts:
+
+```
+execute_script(body, async, context)
+```
+
+`body` is a function body for the script to execute. `async` controls
+whether we return the return value of the function directly, or
+require a callback on the remote side to be called with the return
+value; when it's false we use the [Execute
+Script](https://w3c.github.io/webdriver/#execute-script) semantics and
+use the return value of the function directly, when it's true we use
+the [Execute Async
+Script](https://w3c.github.io/webdriver/#execute-async-script)
+semantics in which the final argument passed to the implicit wrapper
+function is a callback, and the call returns with the value this
+function is called with. `context` is an object that can be resolved
+as a testdriver context id to identify the remote context (see [RFC
+88](https://github.com/web-platform-tests/rfcs/pull/88). The return
+value is a promise that resolves to the value of the script.
+
+For example:
+
+```
+<iframe src="child.html"></iframe>
+<script>
+setup({single_test: true});
+onload = {
+  let value = test_driver.execute_script("return document.body.textContent", false, iframe.contentWindow);
+  assert_equals(value, "PASS");
+  done();
+}
+</script>
+```
+
+## Risks
+
+The async scripting API from testdriver is a bit akward. Maybe we
+should consider automatically adding a local variable called e.g.
+`callback` rather than requring each author to do the `let callback =
+arguments[arguments.length - 1]` dance manually.
+
+## References
+
+[PR 29803](https://github.com/web-platform-tests/wpt/pull/29803)
+contains a prototype implementation of this.