chore(docs): new framework requirements in Protractor 6.0 (angular#3893)

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,80 @@ 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>
 ```
 
 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 you want your framework to be backwards-compatible, you can simply write:
+
+```ts
+if (runner.afterEach) {
+  // Add afterEach caller
+}
+```
+
+Failing to call `runner.afterEach` will cause features like
+`restartBrowserBetweenTests` to fail.  Protractor may also log a warning to the
+console. 
 
 Custom Frameworks
 -----------------
@@ -53,8 +86,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'),