Add missing typings (webdriverio#3319)

## Proposed changes

- Adds type `DesiredCapabilities[]` to the typings and documentation
- Adds property `execArgv` to the typings and documentation
- Adds typings and documentation for the various hooks

[//]: # (Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request. If it fixes a bug or resolves a feature request, be sure to link to that issue.)

## Types of changes

[//]: # (What types of changes does your code introduce to WebdriverIO?)
[//]: # (_Put an `x` in the boxes that apply_)

- [x] Bugfix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

## Checklist

[//]: # (_Put an `x` in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code._)

- [x] I have read the [CONTRIBUTING](https://github.com/webdriverio/webdriverio/blob/master/CONTRIBUTING.md) doc
- [ ] I have added tests that prove my fix is effective or that my feature works
- [x] I have added necessary documentation (if appropriate)

## Further comments

[//]: # (If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...)

Please review thoroughly since I did some assumptions.
I added the missing `execArgv` property but have 3 questions:
- Did not add a default to a constant file since the default is null (I presume). Is that ok? I apparently also did not add a default for the `services` property that I added in a previous MR.
- I made it optional. Is that ok? Looking at the other properties, I am unclear on when it should be optional or not.
- I put it in the `webdriver.tpl.d.ts` file and not in the `webdriverio.tpl.d.ts` file. Is that ok?

### Reviewers: @webdriverio/technical-committee

docs/ConfigurationFile.md

@@ -315,11 +315,12 @@ exports.config = {
     onComplete: function (exitCode, config, capabilities, results) {
     },
     /**
-    * Gets executed when an error happens, good place to take a screenshot
-    * @ {String} error message
+    * Gets executed when a refresh happens.
+    * @param {String} oldSessionId session ID of the old session
+    * @param {String} newSessionId session ID of the new session
     */
-    onError: function(message) {
-    }
+    onReload: function(oldSessionId, newSessionId) {
+    },
     /**
      * Cucumber specific hooks
      */

docs/Options.md

@@ -46,7 +46,7 @@ Defines the capabilities you want to run in your WebDriver session. Check out th
 that helps you to create this object by clicking together your desired capabilities.
 
 Type: `Object`<br>
-Default: `{ browserName: 'firefox' }`<br>
+Default: `{ browserName: 'firefox' }`
 
 **Example:**
 
@@ -109,6 +109,12 @@ An object describing various of suites that can be specified when applying the `
 Type: `Object`<br>
 Default: `{}`
 
+### capabilities
+Like the capabilities section described above, except with the option to specifiy either a [multiremote](Multiremote.md) object, or multiple WebDriver sessions in an array for parallel execution.
+
+Type: `Object`|`Object[]`<br>
+Default: `[{ maxInstances: 5, browserName: 'firefox' }]`
+
 ### outputDir
 Directory to store all testrunner log files including reporter logs and `wdio` logs. If not set all logs are streamed to stdout. Since most reporters are made to log to stdout it is recommended to only use this option for specific reporters where it makes more sense to push report into a file (e.g. junit reporter).
 
@@ -142,7 +148,7 @@ Default: `500`
 ### services
 Services take over a specific job you don't want to take care of. They enhance your test setup with almost no effort. Unlike plugins, they don't add new commands. Instead, they hook themselves up into the test process.
 
-Type: `String[]`<br>
+Type: `String[]|Object[]`<br>
 Default: `[]`
 
 ### framework
@@ -177,9 +183,15 @@ reporters: [
 ]
 ```
 
+### execArgv
+Node arguments to specify when launching child processes
+
+Type: `String[]`
+Default: `null`
+
 ## Hooks
 
-WebdriverIO allows you to set hooks to interfere into the test lifecycle in order to e.g. take screenshot if a test fails. Every hook has as parameter specific information about the lifecycle (e.g. information about the test suite or test). The following hooks are available: `onPrepare`, `beforeSession`, `before`, `beforeSuite`, `beforeHook`, `afterHook`, `beforeTest`, `beforeCommand`, `afterCommand`, `afterTest`, `afterSuite`, `after`, `afterSession`, `onComplete`, `beforeFeature`, `beforeScenario`, `beforeStep`, `afterStep`, `afterScenario`, `afterFeature`.
+WebdriverIO allows you to set hooks to interfere into the test lifecycle in order to e.g. take screenshot if a test fails. Every hook has as parameter specific information about the lifecycle (e.g. information about the test suite or test). The following hooks are available: `onPrepare`, `beforeSession`, `before`, `beforeSuite`, `beforeHook`, `afterHook`, `beforeTest`, `beforeCommand`, `afterCommand`, `afterTest`, `afterSuite`, `after`, `afterSession`, `onComplete`, `onReload`, `beforeFeature`, `beforeScenario`, `beforeStep`, `afterStep`, `afterScenario`, `afterFeature`.
 
 Type: `Function`<br>
 Default: `null`

examples/wdio.conf.js

@@ -301,6 +301,13 @@ exports.config = {
      */
     onComplete: function (exitCode, config, capabilities, results) {
     },
+    /**
+    * Gets executed when a refresh happens.
+    * @param {String} oldSessionId session ID of the old session
+    * @param {String} newSessionId session ID of the new session
+    */
+    onReload: function(oldSessionId, newSessionId) {
+    },
     //
     // Cucumber specific hooks
     beforeFeature: function (feature) {

packages/wdio-cli/src/templates/wdio.conf.tpl.ejs

@@ -338,5 +338,12 @@ exports.config = {
      * @param {<Object>} results object containing test results
      */
     // onComplete: function(exitCode, config, capabilities, results) {
-    // }
+    // },
+    /**
+    * Gets executed when a refresh happens.
+    * @param {String} oldSessionId session ID of the old session
+    * @param {String} newSessionId session ID of the new session
+    */
+    //onReload: function(oldSessionId, newSessionId) {
+    //}
 }

packages/wdio-config/src/constants.js

@@ -57,7 +57,6 @@ export const DEFAULT_CONFIGS = {
     afterSession: [],
     after: [],
     onComplete: NOOP,
-    onError: [],
     onReload: [],
 
     /**
@@ -75,5 +74,5 @@ export const SUPPORTED_HOOKS = [
     'before', 'beforeSession', 'beforeSuite', 'beforeHook', 'beforeTest', 'beforeCommand',
     'afterCommand', 'afterTest', 'afterHook', 'afterSuite', 'afterSession', 'after',
     'beforeFeature', 'beforeScenario', 'beforeStep', 'afterFeature',
-    'afterScenario', 'afterStep', 'onError', 'onReload'
+    'afterScenario', 'afterStep', 'onReload', 'onPrepare', 'onComplete'
 ]

packages/wdio-junit-reporter/tests/__fixtures__/runner.json

@@ -85,7 +85,6 @@
         "afterSuite": [],
         "afterSession": [],
         "after": [],
-        "onError": [],
         "onReload": [],
         "beforeFeature": [],
         "beforeScenario": [],

packages/webdriverio/src/constants.js

@@ -56,6 +56,13 @@ export const WDIO_DEFAULTS = {
     suites: {
         type: 'object'
     },
+    /**
+     * capabilities of WebDriver sessions
+     */
+    capabilities: {
+        type: 'object|object[]',
+        required: true
+    },
     /**
      * Shorten navigateTo command calls by setting a base url
      */
@@ -146,6 +153,20 @@ export const WDIO_DEFAULTS = {
             return true
         }
     },
+    /**
+     * set of WDIO services to use
+     */
+    services: {
+        type: 'string[]|object[]',
+        default: []
+    },
+    /**
+     * Node arguments to specify when launching child processes
+     */
+    execArgv: {
+        type: 'string[]',
+        default: []
+    },
     /**
      * amount of instances to be allowed to run in total
      */
@@ -197,7 +218,6 @@ export const WDIO_DEFAULTS = {
     onComplete: {
         type: 'function'
     },
-    onError: HOOK_DEFINITION,
     onReload: HOOK_DEFINITION,
 
     /**

scripts/templates/webdriver.tpl.d.ts

@@ -220,8 +220,86 @@ declare namespace WebDriver {
         key?: string;
     }
 
+    interface Hooks {
+
+        onPrepare?(
+            config: Options,
+            capabilities: DesiredCapabilities
+        ): void;
+
+        onComplete?(exitCode: number): void;
+
+        onReload?(oldSessionId: string, newSessionId: string): void;
+
+        before?(
+            capabilities: DesiredCapabilities,
+            specs: string[]
+        ): void;
+
+        beforeCommand?(
+            commandName: string,
+            args: any[]
+        ): void;
+
+        beforeHook?(): void;
+
+        beforeSession?(
+            config: Options,
+            capabilities: DesiredCapabilities,
+            specs: string[]
+        ): void;
+
+        beforeSuite?(suite: Suite): void;
+        beforeTest?(test: Test): void;
+        afterHook?(): void;
+
+        after?(
+            result: number,
+            capabilities: DesiredCapabilities,
+            specs: string[]
+        ): void;
+
+        afterCommand?(
+            commandName: string,
+            args: any[],
+            result: any,
+            error?: Error
+        ): void;
+
+        afterSession?(
+            config: Options,
+            capabilities: DesiredCapabilities,
+            specs: string[]
+        ): void;
+
+        afterSuite?(suite: Suite): void;
+        afterTest?(test: Test): void;
+
+         // cucumber specific hooks
+         beforeFeature?(feature: string): void;
+         beforeScenario?(scenario: string): void;
+         beforeStep?(step: string): void;
+         afterFeature?(feature: string): void;
+         afterScenario?(scenario: any): void;
+         afterStep?(stepResult: any): void;
+    }
+
+    interface Suite {
+        file: string;
+        parent: string;
+        pending: boolean;
+        title: string;
+        type: string;
+    }
+
+    interface Test extends Suite {
+        currentTest: string;
+        passed: boolean;
+        duration: any;
+    }
+
     function newSession(
-        options?: Options,
+        options?: Options & Hooks,
         modifier?: (...args: any[]) => any,
         proto?: object,
         commandWrapper?: (commandName: string, fn: (...args: any[]) => any) => any

scripts/templates/webdriverio.tpl.d.ts

@@ -57,6 +57,7 @@ declare namespace WebdriverIO {
         specs?: string[],
         exclude?: string[],
         suites?: object,
+        capabilities: WebDriver.DesiredCapabilities|WebDriver.DesiredCapabilities[],
         outputDir?: string,
         baseUrl?: string,
         bail?: number,
@@ -66,7 +67,8 @@ declare namespace WebdriverIO {
         mochaOpts?: object,
         jasmineNodeOpts?: object,
         reporters?: string[] | object[],
-        services?: string[],
+        services?: string[] | object[],
+        execArgv?: string[]
     }
 
     interface Element<T> {