webdriverio 4.9.10 → 4.10.2

package/docs/guide/services/docker.md

@@ -0,0 +1,145 @@
+name: docker
+category: services
+tags: guide
+index: 13
+title: WebdriverIO - Docker Service
+---
+
+Docker Service
+===========================
+
+This service allows user to seamlessly run test for/using a containerized application by utilizing a popular [Docker](https://www.docker.com/) service.
+Currently it supports two modes of operation:
+- using Docker to host Selenium (similar to Selenium Standalone Service)
+- using Docker to run your containerized application
+
+## Installation
+
+The easiest way is to keep `wdio-docker-service` as a devDependency in your `package.json`.
+
+```json
+{
+  "devDependencies": {
+    "wdio-docker-service": "~1.x"
+  }
+}
+```
+
+You can simply do it by:
+
+```bash
+npm install wdio-docker-service --save-dev
+```
+
+## Configuration
+
+By default, Google Chrome, Firefox and PhantomJS are available when installed on the host system. In order to use the service you need to add docker to your service array:
+
+```js
+// wdio.conf.js
+exports.config = {
+  // ...
+  services: ['docker'],
+  // ...
+  // Options are set here as well
+  dockerLogs: './logs',
+  dockerOptions: { 
+    image: 'selenium/standalone-chrome',
+    healthCheck: 'http://localhost:4444',
+    options: { 
+      p: ['4444:4444'],
+      shmSize: '2g'
+    }    
+  }
+  //...
+};
+```
+
+## Options
+
+### dockerOptions
+Various options required to run docker container
+
+Type: `Object`
+
+Default: `{ 
+    options: {
+        rm: true,
+        cidfile: [path to cidfile]
+    }
+}`
+
+Example:
+
+```javascript
+dockerOptions: {
+    image: 'selenium/standalone-chrome',
+    healthCheck: 'http://localhost:4444',
+    options: {
+        p: ['4444:4444'],
+        shmSize: '2g'
+    }
+}
+```
+
+### dockerOptions.image
+Docker container name tag. Could be local or from Docker HUB.
+
+Type: `String`
+
+Required: `true`
+
+### dockerOptions.healthCheck
+Url to an app exposed by your container. Normally this is a localhost url.
+If healthCheck is not provided, Webdriver will start running tests immediately after Docker container is executed, which
+maybe too early considering that it takes time for web service to start inside a Docker container.
+
+Type: `String`
+
+Example: `http://localhost:4444`
+
+### dockerOptions.options
+Map of options used by `docker run` command. For more details on `run` command click [here](https://docs.docker.com/edge/engine/reference/commandline/run/).
+
+Any single-letter option will be converted to `-[option]` (i.e. `d: true` -> `-d`). 
+
+Any option of two-character or more will
+be converted to `--[option]` (i.e. `rm: true` -> `--rm`). 
+
+For options that may be used more than once 
+(i.e. `-e`,`-add-host`, `--expose`, etc.), please use array notation (i.e. `e: ["NODE_ENV=development", "FOO=bar"]`).
+
+Type: `Object`
+
+Example:
+
+```javascript
+options: {
+    e: ['NODE_ENV=development', 'PROXY=http://myproxy:80']
+    p: ['4444:4444', '5900:5900'],
+    shmSize: '2g'
+}
+```
+
+### dockerOptions.args
+Any arguments you may want to pass into container. Corresponds to `[ARG...]` in Docker run CLI.
+
+Type: `String`
+
+### dockerOptions.command
+Any command you may want to pass into container. Corresponds to `[COMMAND]` in Docker run CLI.
+
+Type: `String`
+
+### onDockerReady
+A callback method which is called when Docker application is ready. Readiness is determined by ability to ping `healthCheck` url.
+
+Type: `Function`
+
+### dockerLogs
+Path to where logs from docker container should be stored
+
+Type: `String`
+
+## Testing Use Cases / Recipes
+Please visit our [Wiki](https://github.com/stsvilik/wdio-docker-service/wiki) for more details.

package/docs/guide/services/webpack-dev-server.md

@@ -12,7 +12,7 @@ This allows you to run a local server with your built static assets using Webpac
 
 ## Installation
 
-``bash
+```bash
 npm install wdio-webpack-dev-server-service --save-dev
 ```
 

package/docs/guide/testrunner/configurationfile.md

@@ -279,7 +279,7 @@ exports.config = {
     beforeHook: function () {
     },
     /**
-     * Hook that gets executed _after_ a hook within the suite starts (e.g. runs after calling
+     * Hook that gets executed _after_ a hook within the suite ends (e.g. runs after calling
      * afterEach in Mocha)
      */
     afterHook: function () {
@@ -307,7 +307,7 @@ exports.config = {
     afterCommand: function (commandName, args, result, error) {
     },
     /**
-     * Function to be executed after a test (in Mocha/Jasmine) or a step (in Cucumber) starts.
+     * Function to be executed after a test (in Mocha/Jasmine) or a step (in Cucumber) ends.
      * @param {Object} test test details
      */
     afterTest: function (test) {

package/docs/guide/testrunner/gettingstarted.md

@@ -39,8 +39,8 @@ Options:
   --waitforTimeout, -w  timeout for all waitForXXX commands (default: 1000ms)
   --framework, -f       defines the framework (Mocha, Jasmine or Cucumber) to run the specs (default: mocha)
   --reporters, -r       reporters to print out the results on stdout
-  --suite               overwrites the specs attribute and runs the defined suite
-  --spec                run only a certain spec file - overrides specs piped from stdin
+  --suite               runs the defined suite, can be combined with --spec
+  --spec                runs a certain spec file, can be combined with --suite - overrides specs piped from stdin
   --cucumberOpts.*      Cucumber options, see the full list options at https://github.com/webdriverio/wdio-cucumber-framework#cucumberopts-options
   --jasmineOpts.*       Jasmine options, see the full list options at https://github.com/webdriverio/wdio-jasmine-framework#jasminenodeopts-options
   --mochaOpts.*         Mocha options, see the full list options at http://mochajs.org

package/docs/guide/testrunner/organizesuite.md

@@ -85,28 +85,48 @@ exports.config = {
 }
 ```
 
-If you now want to run a single suite only you can pass the suite name as cli argument like
+Now, if you want to only run a single suite, you can pass the suite name as cli argument like:
 
 ```sh
 $ wdio wdio.conf.js --suite login
 ```
 
-or run multiple suites at once
+or run multiple suites at once:
 
 ```sh
 $ wdio wdio.conf.js --suite login,otherFeature
 ```
 
-## Run Single Test Suites
+## Run Selected Tests
 
-If you are working on your WebdriverIO tests you don't want to execute your whole suite everytime you added an assertion or any other code. With the `--spec` parameter you can specify which suite (Mocha, Jasmine) or feature (Cucumber) should be run. For example if you only want to run your login test, do:
+In some cases, you may wish to only execute a single test or a subset of your suites. With the `--spec` parameter you can specify which suite (Mocha, Jasmine) or feature (Cucumber) should be run. For example if you only want to run your login test, do:
 
 ```sh
 $ wdio wdio.conf.js --spec ./test/specs/e2e/login.js
 ```
 
+or run multiple specs at once:
+
+```sh
+$ wdio wdio.conf.js --spec ./test/specs/signup.js,./test/specs/forgot-password.js
+```
+
+If the spec passed in is not a path to a spec file, it is used as a filter for the specs defined in your configuration file. To run all specs with the word 'dialog' in them, you could use:
+
+```sh
+$ wdio wdio.conf.js --spec dialog
+```
+
 Note that each test file is running in a single test runner process. Since we don't scan files in advance (see the next section for information on piping filenames to `wdio`) you _can't_ use for example `describe.only` at the top of your spec file to say Mocha to only run that suite. This feature will help you though to do that in the same way.
 
+## Run Suites and Test Specs
+
+This will allow you to run an entire suite along with individual spec's.
+
+```sh
+$ wdio wdio.conf.js --suite login --spec ./test/specs/signup.js
+```
+
 ## Run Multiple, Specific Test Specs
 
 It is sometimes necessary—in the context of continuous integration and otherwise—to specify multiple sets of specs to be run at runtime. WebdriverIO's `wdio` command line utility will accept piped input in the form of filenames (from `find`, `grep`, or others). These filenames will override the list of glob patterns or filenames specified in the configuration file's `spec` list.
@@ -120,3 +140,5 @@ _**Note:** This will_ not _override the `--spec` flag for running a single spec.
 ## Stop testing after failure
 
 With the `bail` option you can specify when WebdriverIO should stop the test run after test failures. This can be helpful when you have a big test suite and want to avoid long test runs when you already know that your build will break. The option expects a number that specifies after how many spec failures it should stop the whole test run. The default is `0` meaning that it always runs all tests specs it can find.
+
+Please see http://webdriver.io/guide/getstarted/configuration.html#bail for additional information on the bail configuration.

package/docs/guide/testrunner/reporters.md

@@ -14,10 +14,16 @@ You can write your own custom reporter for the wdio test runner that fits your n
 var util = require('util'),
     events = require('events');
 
-var CustomReporter = function(options) {
-    // you can access reporter options via
-    // `options.reporterOptions`
-    // ...
+var CustomReporter = function(baseReporter, config, options) {
+    // you can access reporter options via reporterOptions object against your custom reporter
+    // For example,  in your configuration file you have:
+    // reporterOptions: {
+    //     CustomReporter: {
+    //         outputDir: './custom_report'
+    //     }
+    // },
+    // 
+    // then in your custom reporter, you can acess: options.outputDir
 };
 
 /**
@@ -50,6 +56,7 @@ You can register event handler for several events which get triggered during the
 
 ```txt
 'start'
+'runner:start'
 'suite:start'
 'hook:start'
 'hook:end'
@@ -59,6 +66,7 @@ You can register event handler for several events which get triggered during the
 'test:fail'
 'test:pending'
 'suite:end'
+'runner:end'
 'end'
 ```
 

package/docs/guide/testrunner/retry.md

@@ -73,7 +73,7 @@ module.exports = function () {
     /**
      * step definition that runs max 3 times (1 actual run + 2 reruns)
      */
-    this.Given(/^some step definition$/, { retry: 2 }, () => {
+    this.Given(/^some step definition$/, { wrapperOptions: { retry: 2 } }, () => {
         // ...
     })
     // ...

package/docs/guide.md

@@ -43,9 +43,10 @@ $ curl -L https://github.com/mozilla/geckodriver/releases/download/v0.16.0/gecko
 
 Note: Other geckodriver releases are available [here](https://github.com/mozilla/geckodriver/releases).
 
+** 4. Start selenium standalone server**
+
 Start the server by executing the following:
 
-** 4. Start selenium standalone server**
 ```sh
 $ java -jar -Dwebdriver.gecko.driver=./geckodriver selenium-server-standalone-3.5.3.jar
 ```

package/lib/commands/getElementSize.js

@@ -27,7 +27,7 @@
  *
  * @alias browser.getElementSize
  * @param   {String}  selector element with requested size
- * @param   {String*} prop     size to receive (optional "width|height")
+ * @param   {String*} prop     size to receive [optional] ("width" or "height")
  * @return {Object|Number}    requested element size (`{ width: <Number>, height: <Number> }`) or actual width/height as number if prop param is given
  * @uses protocol/elements, protocol/elementIdSize
  * @type property

package/lib/commands/getValue.js

@@ -18,7 +18,7 @@
  * @alias browser.getValue
  * @param   {String} selector input, textarea, or select element
  * @return {String}          requested input value
- * @uses protocol/elements, protocol/elementIdAttribute
+ * @uses protocol/elements, protocol/elementIdProperty
  * @type property
  *
  */
@@ -34,12 +34,12 @@ let getValue = function (selector) {
             throw new CommandError(7, selector || this.lastResult.selector)
         }
 
-        let elementIdAttributeCommands = []
+        let elementIdPropertyCommands = []
         for (let elem of res.value) {
-            elementIdAttributeCommands.push(this.elementIdAttribute(elem.ELEMENT, 'value'))
+            elementIdPropertyCommands.push(this.elementIdProperty(elem.ELEMENT, 'value'))
         }
 
-        return this.unify(elementIdAttributeCommands, {
+        return this.unify(elementIdPropertyCommands, {
             extractValue: true
         })
     })

package/lib/commands/touchAction.js

@@ -49,12 +49,20 @@
             'release'
         ])
 
+        // multi action using x y variables
+        // moveTo location is relative from the starting coordinate
+        browser.touchAction([
+            { action: 'press', x: 20, y: 550 },
+            { action: 'moveTo', x: 0, y: -500},
+            'release'
+        ])
+
         // drag&drop to element
         screen.touchAction([
             'press',
             { action: 'moveTo', selector: '//UIAApplication[1]/UIAElement[2]' },
             'release'
-        ]))
+        ])
     });
 
     :multiTouchAction.js
@@ -62,7 +70,7 @@
         // drag&drop with two fingers 200px down
         browser.touchAction([
             [{action: 'press', x:  10, y: 10}, { action: 'moveTo', x: 0, y: 200 }, 'release'],
-            [{action: 'press', x: 100, y: 10}, { action: 'moveTo', x: 0, y: 200 }, 'release']]
+            [{action: 'press', x: 100, y: 10}, { action: 'moveTo', x: 0, y: 200 }, 'release']
         ])
     })
  * </example>

package/lib/protocol/elementIdProperty.js

@@ -0,0 +1,33 @@
+/**
+ *
+ * Get the value of an element's property.
+ *
+ * @param {String} ID             ID of a WebElement JSON object to route the command to
+ * @param {String} propertyName  property name of element you want to receive
+ *
+ * @return {String|null} The value of the property, or null if it is not set on the element.
+ *
+ * @see  https://w3c.github.io/webdriver/webdriver-spec.html#dfn-get-element-property
+ * @type protocol
+ *
+ */
+
+import { ProtocolError } from '../utils/ErrorHandler'
+import { isUnknownCommand } from '../helpers/utilities'
+
+export default function elementIdProperty (id, propertyName) {
+    if ((typeof id !== 'string' && typeof id !== 'number') || typeof propertyName !== 'string') {
+        throw new ProtocolError('number or type of arguments don\'t agree with elementIdProperty protocol command')
+    }
+
+    return this.requestHandler.create(`/session/:sessionId/element/${id}/property/${propertyName}`).catch((err) => {
+        /**
+         * use old path if W3C path failed
+         */
+        if (isUnknownCommand(err)) {
+            return this.elementIdAttribute(id, propertyName)
+        }
+
+        throw err
+    })
+}

package/lib/protocol/keys.js

@@ -10,9 +10,6 @@
  * [here](https://w3c.github.io/webdriver/webdriver-spec.html#keyboard-actions).
  * To do that, the value has to correspond to a key from the table.
  *
- * This command is deprecated and will be removed soon. Make sure you don't use it in your
- * automation/test scripts anymore to avoid errors.
- *
  * @param {String|String[]} value  The sequence of keys to type. An array must be provided. The server should flatten the array items to a single string to be typed.
  *
  * @see  https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#sessionsessionidkeys

package/lib/protocol/toggleTouchIdEnrollment.js

@@ -17,5 +17,8 @@
  *
  */
 export default function toggleTouchIdEnrollment () {
-    return this.requestHandler.create('session/:session_id/appium/simulator/toggle_touch_id_enrollment')
+    return this.requestHandler.create({
+        path: '/session/:sessionId/appium/simulator/toggle_touch_id_enrollment',
+        method: 'POST'
+    })
 }

package/lib/protocol/touchId.js

@@ -20,5 +20,8 @@
  */
 
 export default function touchId (match = true) {
-    return this.requestHandler.create('/session/:sessionId/appium/simulator/touch_id', { match })
+    return this.requestHandler.create({
+        path: '/session/:sessionId/appium/simulator/touch_id',
+        method: 'POST'
+    }, { match })
 }