Getting Started
Welcome to the WebdriverIO documentation. It will help you to get started fast. If you run into problems you can find help and answers on our Gitter Channel or you can hit me on Twitter. Also, if you encounter problems in starting up the server or running the tests after following this tutorial, ensure that the server and the geckodriver are listed in your project directory. If not, re-download them per steps 2 and 3 below.
The following will give you a short step by step introduction to get your first WebdriverIO script up and running.
Taking the first step
Let's suppose you have Node.js already installed. First thing we need to do is to download a browser driver that helps us automate the browser. To do so we create an example folder first:
Create a simple test folder
$ mkdir webdriverio-test && cd webdriverio-test
While still in this test folder:
Download Geckodriver
Download the latest version of geckodriver for your environment and unpack it in your project directory:
Linux 64 bit
$ curl -L https://github.com/mozilla/geckodriver/releases/download/v0.21.0/geckodriver-v0.21.0-linux64.tar.gz | tar xz
OSX
$ curl -L https://github.com/mozilla/geckodriver/releases/download/v0.21.0/geckodriver-v0.21.0-macos.tar.gz | tar xz
Note: Other geckodriver releases are available here. In order to automate other browser you need to run different drivers. You can find a list with all drivers in the awesome-selenium readme.
Start Browser Driver
Start Geckodriver by running:
$ /path/to/binary/geckodriver --port 4444
This will start Geckodriver on localhost:4444
with the WebDriver endpoint set to /
. Keep this running in the background and open a new terminal window. Next step is to download WebdriverIO via NPM:
Download WebdriverIO
By calling:
$ npm install webdriverio
Create Test File
Create a test file (e.g. test.js
) with the following content:
const { remote } = require('webdriverio');
(async () => {
const browser = await remote({
logLevel: 'error',
path: '/',
capabilities: {
browserName: 'firefox'
}
});
await browser.url('http://webdriver.io');
const title = await browser.getTitle();
console.log('Title was: ' + title);
await browser.deleteSession();
})().catch((e) => console.error(e));
Run your test file
Make sure you have at least Node.js v8.11.2 or higher installed. To update your current running Node.js version install nvm and follow their instructions. Once that is done run the test script by calling:
$ node test.js
this should output the following:
Title was: WebdriverIO · Next-gen WebDriver test framework for Node.js
Yay, Congratulations! You've just run your first automation script with WebdriverIO. Let's step it up a notch and create a real test.
Let's get serious
(If you haven't already, navigate back to the project root directory)
This was just a warm up. Let's move forward and run WebdriverIO with the test runner. If you want to use WebdriverIO in your project for integration testing we recommend to use the test runner because it comes with a lot of useful features that makes your life easier. With WebdriverIO v5 and up the testrunner has moved into the wdio-cli
NPM package. To get started, we need to install this first:
$ npm i --save-dev wdio-cli
Generate Configuration File
To do that just run the configuration utility:
$ ./node_modules/.bin/wdio config
A question interface pops up. It will help to create the config easy and fast. If you are not sure what to answer follow this answers:
Q: Where should your tests be launched?
A: local
Q: Shall I install the runner plugin for you?
A: Yes
Q: Where do you want to execute your tests?
A: On my local machine
Q: Which framework do you want to use?
A: mocha
Q: Shall I install the framework adapter for you?
A: Yes (just press enter)
Q: Do you want to run WebdriverIO commands synchronous or asynchronous?
A: sync (just press enter, you can also run commands async and handle promises by yourself but for the sake of simplicity let's run them synchronously)
Q: Where are your test specs located?
A: ./test/specs/*/.js (just press enter)
Q: Which reporter do you want to use?
A: dot (just press space and enter)
Q: Shall I install the reporter library for you?
A: Yes (just press enter)
Q: Do you want to add a service to your test setup?
A: none (just press enter, let's skip this for simplicity)
Q: Level of logging verbosity:
A: trace (just press enter)
Q: In which directory should screenshots gets saved if a command fails?
A: ./errorShots/ (just press enter)
Q: What is the base url?
A: http://localhost (just press enter)
That's it! The configurator now installs all required packages for you and creates a config file with the name wdio.conf.js
. Next step is to create your first spec file (test file).
Create Spec Files
For that create a test folder like this:
$ mkdir -p ./test/specs
Now let's create a simple spec file in that new folder:
var assert = require('assert');
describe('webdriver.io page', function() {
it('should have the right title - the fancy generator way', function () {
browser.url('http://webdriver.io');
var title = browser.getTitle();
assert.equal(title, 'WebdriverIO - WebDriver bindings for Node.js');
});
});
Kick Off Testrunner
The last step is to execute the test runner. To do so just run:
$ ./node_modules/.bin/wdio wdio.conf.js
Hurray! The test should pass and you can start writing integration tests with WebdriverIO. If you are interested in more in depth video on-boarding tutorials, feel free to check out our very own course called learn.webdriver.io. Also our community has collected a lot of boilerplate projects that can help you to get started.