@testim/testim-cli/webdriverio/docs/guide/getstarted/v3.md

Command line interface for running Testing on you CI

name: v3
category: getstarted
tags: guide
index: 0
title: WebdriverIO - What's new in WebdriverIO?
---

# What's new in WebdriverIO v3?

Some big changes came along with `v3`. We've rewritten the whole core to an ajax/promise based monad.
Instead of implementing complex command scheduler or request queues we build the whole library on top
of a monad construction. This allows us to chain commands as we are used to and keep stacktraces sane.
In addition to that we wanted to have a 1st level promise support. Therefor we used the [Q library](https://github.com/kriskowal/q)
(there are already [plans](https://github.com/webdriverio/webdriverio/issues/498) to move to native Promises)
to integrate promises into the monad system. This works astoundingly well. Each command execution represents
a promise. If you chain commands, the command waits until the previous got resolved. On top of that, the optional
modifer that you can pass to a monad makes the library incredible flexible and extensible.

## Where do I have to change my test?

Actually you should be fine with most of your tests. Except all execute commands `v3` will support the good old
callbacks, so tests like

```js
it('should test something', function(done) {
  client
    .click('#button')
    .getValue('#someInput', function(err, value) {
      expect(err).to.be.undefined;
      expect(value).to.be.exactly('some value');
    })
    .call(done);
});
```

should still pass after moving to `v3`. However I strongly recommend to rewrite the tests as you can save
a lot of obsolete code. Most test frameworks support Promises these days so we should make use of it:

```js
it('should test something', function() {
  return client.click('#button').getValue('#someInput').then(function(value) {
    expect(value).to.be.exactly('some value');
  });
});
```

Looks great doesn't it? Instead of callbacks always call the `then` function if you are interested in the
result of the command. If the command fails for whatever reasons it throws an exception and notifies the
test framework, no unnecessary error checks anymore.

### Handling asynchronicity in addCommand

In `v2.x` the function parameter used to had a callback that should get called once you are done with
your steps. Here is an example:

```js
client.addCommand("getUrlAndTitle", function(customVar, cb) {
    this.url(function(err,urlResult) {
        this.getTitle(function(err,titleResult) {
            var specialResult = {url: urlResult.value, title: titleResult};
            cb(err,specialResult);
            console.log(customVar); // "a custom variable"
        })
    });
});
```

With `v3` we switched over to an promised based execution flow. Therefor the callback parameter is gone
and gets replaced by a promise you need to return in tha function. Once that promise is resolved the
command queue continues. The example above looks in `v3` like this:

```js
client.addCommand("getUrlAndTitle", function(customVar) {
    return this.url().then(function(urlResult) {
        return this.getTitle().then(function(titleResult) {
            console.log(customVar); // "a custom variable"
            return { url: urlResult.value, title: titleResult };
        });
    });
});
```

## What else?

Here is a list of thing that got introduced with `v3`

- Finally this release includes the Multiremote functionality. It allows you to run multiple instances at
  the same time and therefor enables integration tests of applications that require more then one user to
  get tested. See more in the [multiremote section](/guide/usage/multiremote.html).
- WebdriverIO provides now an own test runner to run test in parallel and to help you get your tests up-
  and running quickly. It is called `wdio` and takes a config file as parameter. After you've defined your
  capabilities and test specs in that config file just run the test runner to run test in parallel. See more
  in the [test runner section](/guide/testrunner/gettingstarted.html).
- Due to the new monad based core WebdriverIO is now able to chain selectors. This makes querying deep nested
  elements super easy. Checkout the [selector section](/guide/usage/selectors.html) for more information.
- Removed the `waitFor` command as it is basically the same as `waitForExist`
- Added [`debug`](/api/utility/debug.html) command to help you debug your tests. It stops the queue and allows
  you to jump into the browser to open the dev tools and to check the state of your app. After you are done
  with debugging you can jump back into your terminal, press enter and continue run your test.