Fortress of Solitude – Configuring WebdriverIO
In this chapter, we will install WebdriverIO and its dependencies. There are two approaches, and we will discuss the advantages of each. It is also important to keep the versions of the dependencies up to date. To help with this, we will use Yarn to keep our package.json and yarn.lock files up to date.
The setup instructions for WDIO can be found in the Getting Started section on the official website (https://webdriver.io/docs/gettingstarted):
Figure 2.1 – Getting Started
Figure 2.2 – Current documentation indicators for version 7.x
In this section, we'll cover the following main topics:
- WebdriverIO setup
- Building and installing the project dependencies
- Making out first commit
Be sure you are viewing the latest version of WDIO 8.0. Googling questions about WDIO features can lead to support pages of prior versions.
- Custom configuration while answering a series of questions
- Cloned from an existing project on GitHub
For this project, we will show the questions and the selected answers. The second option, cloning the boilerplate project approach, is described in the following section.
> yarn create wdio .
The WDIO robot will appear, and a list of configuration questions will be presented:
Figure 2.3 – WDIO initialization from the code TERMINAL window
The initialization will ask how to configure WDIO from scratch. Here is the list of settings for WebDriver 8.0. There are several options, and many will use the default. Each item with a star (
*) shows the choice selected at setup:
WebdriverIO is always being updated. These questions themselves should be similar for both Mac and Windows users. However, the order, phrasing, and selection details do change slightly as new features are added.
Figure 2.4 – Settings
? What type of testing would you like to do? (Use arrow keys)
- > (*) E2E Testing - of Web or Mobile Applications
- ( ) Component or Unit Testing - in the browser
- > https://webdriver.io/docs/component-testing
- ( ) Desktop Testing - of Electron Applications
- > https://webdriver.io/docs/desktop-testing/electron
- ( ) Desktop Testing - of MacOS Applications
- > https://webdriver.io/docs/desktop-testing/macos
? Where is your automation backend located? (Use arrow keys)
- > (*) On my local machine (default)
- ( ) In the cloud using Experitest
- ( ) In the cloud using Sauce Labs
- ( ) In the cloud using Browserstack or Testingbot or LambdaTest or a different service
- ( ) I have my own Selenium cloud
Today, there are many cloud options, including
LambdaTest. For this book, we will install the automation backend on our local Mac or Windows machine.
Next is the environment type. For these purposes, we will use
? Which environment would you like to automate? (Use arrow keys)
- (*) Web - web applications in the browser
- ( ) Mobile - native, hybrid, and mobile web apps, on Android or iOS
? With which browser should we start? (Press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
- (*) Chrome
- ( ) Firefox
- ( ) Safari
- ( ) Microsoft Edge
Next is the reporting framework type. For this book, we will be using Jasmine. However, much of the code that’s supplied will apply to all listed frameworks:
? Which framework do you want to use? (Use arrow keys)
- ( ) Mocha (https://mochajs.org/)
- ( ) Mocha with Serenity/JS (https://serenity-js.org/)
- (*) Jasmine (https://jasmine.github.io/)
- ( ) Jasmine with Serenity/JS (https://serenity-js.org/)
- ( ) Cucumber (https://cucumber.io/)
- ( ) Cucumber with Serenity/JS (https://serenity-js.org/)
Out of the box, WebdriverIO uses Mocha by default. However, it also supports Jasmine and can be combined with Chai for advanced assertions. Cucumber is an extra layer of abstraction framework that hides the core code. This allows fewer technical resources to create tests from Feature files. Cucumber is outside the scope of this book, but the techniques described can be implemented in a Cucumber WDIO project. Next, we will tell WDIO this is a Typescript project:
? Do you want to use a compiler? (Use arrow keys
- ( ) Babel (https://babeljs.io/)
- (*) TypeScript (https://www.typescriptlang.org/)
- ( ) No!
Question: What is Babel and is it needed?
Question: How to know what features are available in different browsers and versions?
The caniuse.com website provides descriptive tables of the different ECMAScript features that are supported:
? Do you want WebdriverIO to autogenerate some test files?
This will automatically set up a sample test to run to ensure WebdriverIO is working. It is also where we will build a framework unit test to check features are working. Oh yes, we are developers, and our automation project has its own unit and integration tests.
The following is the default path for the TypeScript sample test cases and should not be changed:
? Where should be the location of your specs files?
Tests can be organized into feature sub-folders and smoke tests under the specs folder. Notice that because we selected TypeScript in the prior question, the test extensions (.js) replaced with .ts.
? Do you want to use page objects (https://martinfowler.com/bliki/PageObject.html)?
? Where are your page objects located? ./test/pageobjects/**/*.ts
Now, we want to configure our reporters.
Which reporter do you want to use?
- (*) spec
- ( ) dot
- ( ) junit
- (*) allure
- ( ) video
- ( ) mochawesome
- ( ) slack
WebdriverIO supports a wide variety of reporters. For this small sample, we will start with the spec and allure reporters. Note that WDIO even supports a Video option. You may notice that Slack is included. In the final chapter of this book, we will be using Jenkins to send update messages to a Slack channel.
? Do you want to add a plugin to your test setup?
- ( ) wait-for: utilities that provide functionalities to wait for certain conditions till a defined task is complete.
- > https://www.npmjs.com/package/wdio-wait-for
- ( ) angular-component-harnesses: support for Angular component test harnesses
- > https://www.npmjs.com/package/@badisi/wdio-harness
- ( ) Testing Library: utilities that encourage good testing practices laid down by dom-testing-library.
- > https://testing-library.com/docs/webdriverio-testing-library/intro
In our framework, we will have an advanced approach for waiting for page synchronization. This option will be left as-is.
? Do you want to add a service to your test setup?
- ( ) vscode
- ( ) eslinter-service
- ( ) lambdatest
- ( ) crossbrowsertesting
- ( ) vscode
- ( ) docker
- ( ) slack
34 additional services are integrated into WDIO, including Slack, Cross Browser Testing (Selenium Standalone), and ES-Linter. Covering them all is beyond the scope of this book.
The WebdriverIO Visual Studio Code (VS Code) service allows us to seamlessly test extensions from end to end in the VS Code Desktop ID. By providing a path to your extension, the service does the rest, as follows:
- 🏗 Installs VS Code (either stable, insiders, or a specified version).
- ⬇ Download Chromedriver specific to the given VS Code version.
- 🚀 Enables you to access the VS Code API from your tests.
- 🖥 Starts VS Code with custom user settings (including support for VS Code on Ubuntu, macOS, and Windows).
- 🌐 Serves VS Code from a server to be accessed by any browser for testing web extensions.
- 📔 Bootstraps page objects with locators that match your VS Code version.
The next question asks you to enter the landing page for the application under test. For this, we will use the default provided as the sample tests use this to navigate internally to a website for testing.
? What is the base URL?
A base landing page ensures we do not repeatedly add code to navigate to the same landing page. Later in this book, we will see how to customize this value. For the moment, we will use the internet sandbox for testing.
The final installation step is to have npm download and install all the packages. While this part can be performed by the installer, we need to make one modification. Choose No for the final question.
? Do you want me to run `npm install` (Y/n)
We will be using Yarn rather than npm as our package manager due to its speed. This completes the setup for installing and configuring WebdriverIO from the wizard. Another option is to clone an existing project, which will be covered next. Skip to the Installing and configuring WebdriverIO section if you do not plan to clone from an existing project.
> yarn install
Option 1 – cloning WebdriverIO from a boilerplate project
An alternate way to set up WDIO is to use a preconfigured WDIO boilerplate project from the WDIO GitHub repo. This means that less troubleshooting might be needed. We can choose from many preconfigured boilerplate projects with all the necessary components.
For this project, we will fork the
Jasmine TypeScript Boilerplate project from GitHub:
Figure 2.5 – The Jasmine TypeScript boilerplate project on GitHub
Click the jasmine-boilerplate link. This will allow us to create our own version via the Code button:
Figure 2.6 – Copying the project URL from GitHub
Figure 2.7 – Cloning from the source path to the local destination
Click Clone; the project will be put in the
Figure 2.8 – The project’s Explorer icon in VS Code
Click the Explorer icon in the top-left corner of VS Code and open the
Then, click Open Folder, navigate to the
repo\wdio folder, and click Open:
Figure 2.9 – Trusting the authors of a project
With that, we have covered the clone installation approach. Next, we will install everything.
Building and installing the project dependencies
> yarn install
This will bring in all the associated packages to run the project. Sometime in the future, vulnerabilities may occur and we will have to update our packages. We can use Yarn to check which packages are current and which are outdated:
> yarn outdated
The output can be seen in the following screenshot:
Figure 2.10 – Displaying the outdated package
> yarn upgrade-interactive
We will see the following output:
Figure 2.11 – Interactive package list for upgrading
This gives us the most flexibility when we’re keeping our project packages up to date.
If you want to clear the Terminal, use cls in Windows or Ctrl + K or clear on Mac.
After the installation, the yarn.lock file will be updated and the node_modules folder will have all the supporting dependencies downloaded. This contains the expanded list of packages, which has been included to support the packages in package.json. The
yarn.lock file will never need to be edited.
At this point, we should point out that the WebdriverIO setup assumes that a novice user may not know what to do to bring in all the supporting packages:
Figure 2.12 – WebdriverIO with TypeScript successfully installed
For Windows users:
> npx wdio --version
For Mac users:
> wdio --version
We made it! All the supported features have been added to the package.json file. WDIO even gives us a hint to try out our first test –
Figure 2.13 – WebdriverIO gives us a hint on how to run the first test
This has set up WebdriverIO and created a sample test that can be executed with the following yarn command:
> yarn wdio
This results in the following output:
Figure 2.14 – Output of yard command
Tests can also be executed by running a command. Let’s take a look at the options for both Windows and Mac:
For Windows users:
> npx wdio run test/wdio.conf.ts
For Mac users:
> wdio run test/wdio.conf.ts
All the test examples can be found in this book’s GitHub repository: https://github.com/PacktPublishing/Enhanced-Test-Automation-with-WebdriverIO.
This runs the sample tests with basic output detail to the Terminal window from the spec Reporter window:
Figure 2.15 – Pass results shown in the spec report from the sample WDIO test
Now that we have set up our project, either by answering the initial configuration questions or cloning an existing project, we are ready to look at the configurations and file settings of our new WDIO automation project:
Figure 2.16 – All project files
This will display all the files and folders in the project. There are quite a lot of them, so we will cover the important ones here. Open the
README.md file first.
For any project, the
README file is the best place to start. It gives us critical information about how the project is configured, its features, and, most importantly, how to quick-start a sample test.
Next, open the
This is where much of the
Node.js configuration occurs:
Figure 2.17 – All devDependancies in the wdio project
What is the
yarn.lock file contains the full list of required project packages, including ones that support other packages in package.json. It is massive, but don’t worry – you will never have to change it. Yarn Package Manager handles all of this. Whew!
Let’s run Yarn Package Manager with the
install command to get everything loaded and up to date:
> yarn install
This can be seen in the following screenshot:
Figure 2.18 – Building the project using Yarn Package Manager
Making our first commit
Now that we have our first test running, it is time to bring it all to our fortress of solitude – by committing it to our local repo and then to the GitHub repository.
Ignoring files in the Git repository
Before we make our first commit to the Git repo, we need to ignore some files. Once we have set up our WDIO project, VS Code might suggest that the
node_modules folder should be included in the
Figure 2.19 – VS Code detects that the node_modules folder can be ignored
We never want to commit this folder to our Git repo as it gets updated constantly by npm. Having
npm create the folder contents on the fly with the most up-to-date versions is better:
Figure 2.20 – GitHub Desktop indicates over 12,000 files to be committed to the new repo
This is far more files than we need.
Figure 2.21 – A .gitignore file contains files and folders that should not be committed
The same goes for our Allure report and results folders. These files will be rebuilt repeatedly after each test and will not need to be under version control. Once these tests are run from Jenkins, prior runs can be preserved there temporarily or permanently.
By simply adding and saving the
.gitignore file, the list of files changes dramatically:
Figure 2.22 – The repo now only stores the files
.gitignore file is saved, we will see the changes reflected in GitHub Desktop with a manageable size of just eight files.
Never store passwords in the repo. A password should be provided by a secure data provider service such as Vault or AWS Secrets. If no such option exists, then a password file could be referenced in the folder above the project. Otherwise, storing such a credential file in the project requires adding it to the
.gitignore file for security.
One of the first bugs I found in my career was related to passwords. Here, the user had the option to reset their password with a random string of characters. This page would occasionally crash. The reason was that the requirement had the password generated from all 128 ASCII characters. This included BELL, unprintable characters, as well as ones that were difficult to type on the keyboard. The real problem was that this set included angle brackets (
>). The page would only crash when a new password was generated with one of those two characters, as they were interpreted as opening or closing HTML tags on the page.
There are tools that IT security uses to detect passwords in repos, but they often only check the
master repos and ignore the later
feature branches. This, too, is a security risk. Always clean up old branches, as this can be considered a security operations center (SOC) II compliance violation, even if the passwords have long since expired.
We can now add a summary description and optional details. Simply click Commit to main – all our new files will be committed to our local main branch:
Figure 2.23 – Adding a comment and details to a local commit
Figure 2.24 – GitHub Desktop shows that all changes have been committed and suggests pushing any new changes
But what if you need to add new functionality that will take a few days to complete?
To be a part of an automation team, you may be asked to add new and complex functionality. If this takes a few days, we might consider feature branching. A new branch is created from
main. Your changes will be committed to your branch, and changes from
main will be brought in periodically:
Figure 2.25 – Adding a new branch in GitHub Desktop from main
For this book, the final state of the framework will be in a branch named after this chapter. The
main branch will contain the final project.
In this chapter, we installed WebdriverIO with several options added to a set of configuration questions. We also showed how Yarn can keep dependencies current. Lastly, we showed how to make a commit to the repo from GitHub Desktop.
If you run into issues, check the Appendix at the end of this book. There, you will find a detailed list of common and arcane issues with causes, explanations, and resolutions. It also includes a node command cheatsheet for many of these initial processes.
In the next chapter, we will explore the files and connections in the
wdio config file and look at different ways to debug our code.