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.

Closes #3893

Author: sjelin

Diff for: 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: Array<{
+    description: string,
+    assertions: Array<{
+      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

Diff for: 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'),