chore(docs): new framework requirements in Protractor 6.0

Also converted the code in `lib/frameworks/README.md` to typescript.  Also
exported the type of `Runner` so that framework-writers can use typescript.

Part of angular#3893

lib/frameworks/README.md

@@ -3,47 +3,91 @@ Framework Adapters for Protractor
 
 Protractor can work with any test framework that is adapted here.
 
-Each file details the adapter for one test framework. Each file must export a `run` function with the interface:
+Each file details the adapter for one test framework. Each file must export a
+`run` function with the interface:
 
-```js
+```ts
 /**
  * @param {Runner} runner The Protractor runner instance.
  * @param {Array.<string>} specs A list of absolute filenames.
- * @return {q.Promise} Promise resolved with the test results
+ * @return {Promise.<Object>} Promise resolved with the test results. See
+ * "Requirements" section for details.
  */
-exports.run = function(runner, specs)
+export let run: (runner: Protractor.Runner, specs: string) => Promise<Object>
+```
+
+It is recommended that it also export a `protractorVersion` property:
+
+```ts
+/**
+ * The version of Protractor this framework was written for. Do not use syntax
+ * like "^6.0.0" - name a specific version of Protractor. This property is
+ * optional but recommended.
+ *
+ * @example "6.0.0"
+ * @type {string=}
+ */
+export let protractorVersion: string;
 ```
 
 Requirements
 ------------
 
- - `runner.emit` must be called with `testPass` and `testFail` messages. These
- messages must be passed a `testInfo` object, with a `name` and `category`
- property. The `category` property could be the name of the `describe` block
- in jasmine/mocha, the `Feature` in cucumber, or the class name in something
- like jUnit. The `name` property could be the name of an `it` block in
- jasmine/mocha, the `Scenario` in cucumber, or the method name in something
- like jUnit.
-
- - `runner.runTestPreparer` must be called before any tests are run.
-
- - `runner.getConfig().onComplete` must be called when tests are finished.
- It might return a promise, in which case `exports.run`'s promise should not
- resolve until after `onComplete`'s promise resolves.
-
- - The returned promise must be resolved when tests are finished and it should return a results object. This object must have a `failedCount` property and optionally a `specResults`
- object of the following structure:
- ```
- specResults = [{
- description: string,
- assertions: [{
- passed: boolean,
- errorMsg: string,
- stackTrace: string
- }],
- duration: integer
- }]
- ```
+- `runner.emit` must be called with `testPass` and `testFail` messages. These
+ messages must be passed a `testInfo` object with the following structure:
+
+ ```ts
+ testInfo: {
+ category: string,
+ name: string
+ }
+ ```
+
+ The `category` property could be the name of the `describe` block in
+ jasmine/mocha, the `Feature` in cucumber, or the class name in something like
+ jUnit.
+ The `name` property could be the name of an `it` block in jasmine/mocha, the
+ `Scenario` in cucumber, or the method name in something like jUnit.
+
+- `runner.runTestPreparer` must be called after the framework has been
+ initialized but before any spec files are run. This function returns a
+ promise which should be waited on before executing tests.
+
+- `runner.getConfig().onComplete` must be called when tests are finished.
+ It might return a promise, in which case `exports.run`'s promise should not
+ resolve until after `onComplete`'s promise resolves.
+
+- The returned promise must be resolved when tests are finished and it should
+ return a results object. This object must have a `failedCount` property and
+ optionally a `specResults` object of the following structure:
+
+ ```ts
+ specResults: [{
+ description: string,
+ assertions: [{
+ passed: boolean,
+ errorMsg: string,
+ stackTrace: string
+ }],
+ duration: integer
+ }]
+ ```
+
+### Future requirements
+
+In Protractor 6.0, the following additional requirement will be added:
+
+- `runner.afterEach` will have to be called after each test finishes. It will
+ return a promise, which should be waited for before moving onto the next test.
+
+ If your framework does not export a `protractorVersion` property which is at
+ least 6.0.0, and `testPass` or `testFail` are emitted before
+ `runner.afterEach` is called, Protractor will assume your framework is old and
+ does not support `runner.afterEach`. In this case, Protractor will call
+ `runner.afterEach` inside the listener for `testPass` or `testFail`.
+ Protractor will log warnings to the console if important asynchronous work
+ in `runner.afterEach` needed to finish before the next test started, since it
+ can't wait on a Promise from inside an event listener.
 
 Custom Frameworks
 -----------------
@@ -53,8 +97,8 @@ Protractor core please send a PR so it can evaluated for addition as an
 official supported framework. In the meantime you can instruct Protractor
 to use your own framework via the config file:
 
-```js
-exports.config = {
+```ts
+export let config: Protractor.Config = {
  // set to "custom" instead of jasmine/mocha
  framework: 'custom',
  // path relative to the current config file

lib/index.ts

@@ -3,6 +3,7 @@ import {ElementArrayFinder, ElementFinder} from './element';
 import {ProtractorExpectedConditions} from './expectedConditions';
 import {ProtractorBy} from './locators';
 import {Ptor} from './ptor';
+import {Runner} from './runner';
 
 // Re-export selenium-webdriver types.
 export {ActionSequence, Browser, Builder, Button, Capabilities, Capability, error, EventEmitter, FileDetector, Key, logging, promise, Session, until, WebDriver, WebElement, WebElementPromise} from 'selenium-webdriver';
@@ -14,6 +15,7 @@ export {ElementArrayFinder, ElementFinder} from './element';
 export {ProtractorExpectedConditions} from './expectedConditions';
 export {ProtractorBy} from './locators';
 export {Ptor} from './ptor';
+export type Runner = Runner;
 
 export let utils = {
  firefox: require('selenium-webdriver/firefox'),