From c194af8c8d1ab5723fc82c0078aa20ab116240b6 Mon Sep 17 00:00:00 2001 From: Sammy Jelin Date: Thu, 29 Dec 2016 20:11:25 -0800 Subject: [PATCH] chore(docs): new framework requirements in Protractor 6.0 (#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 #3893 --- lib/frameworks/README.md | 99 ++++++++++++++++++++++++++-------------- lib/index.ts | 2 + 2 files changed, 68 insertions(+), 33 deletions(-) diff --git a/lib/frameworks/README.md b/lib/frameworks/README.md index 7f618ca10..a0efc6f2f 100644 --- a/lib/frameworks/README.md +++ b/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.} specs A list of absolute filenames. - * @return {q.Promise} Promise resolved with the test results + * @return {Promise.} 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 ``` 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 diff --git a/lib/index.ts b/lib/index.ts index dbf197023..f8394c575 100644 --- a/lib/index.ts +++ b/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'),