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

Tip

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.

The WDIO team works hard to make everything easy to install, as described in the documentation. WDIO can be set up in two ways:

• 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.

Option 1 – required steps to start installing WebdriverIO 8.0 for TypeScript

Navigate from the TERMINAL window to the \repos\wdio folder. The quickest way to set up a WDIO project quickly from Yarn is to type yarn create wdio, ending with a dot (.):

> 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:

Note

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 Experitest, Sauce Labs, BrowserStack, Testingbot, and 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 Web:

? 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

Then, select the browser(s) we will be using. Select the default of Chrome. Note that we can add others later:

? 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?

Babel (https://babeljs.io/) is a JavaScript transpiler. Because JavaScript is implemented differently in different browsers, a transpiler is used to transform our code to an older JavaScript version. Some features are not implemented in certain browsers, such as async/await, depending on what browser version we are testing against. So, a transpiler allows us to have our framework be backward compatible. Although this is a TypeScript project, we do not need the TypeScript transpiler.

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:

We will be creating our tests in TypeScript, which is a superset of JavaScript. The Typescript transpiler will be used. Now to get a quick startup sample script.

? Do you want WebdriverIO to autogenerate some test files?

(Y/n) Yes

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?

./test/specs/**/*.ts

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)?

Yes

This sets up a Page Object Model folder structure for our project.

? 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.

If the application under test (AUT) is an Angular project, it is recommended to use the Angular Component Harnesses configuration.

? Do you want to add a service to your test setup?

• ( ) vscode
• ( ) eslinter-service
• ( ) lambdatest
• ( ) crossbrowsertesting
• ( ) vscode
• ( ) docker
• ( ) slack

Note

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?

http://localhost

This is the base landing page that our tests will launch.

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)

No

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.

Because we are using Yarn as our package manager instead of npm, we will need to remove the package-lock.json file and run the yarn install command to build the equivalent yarn.lock file.

> 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

Click Code. Multiple choices for cloning the project will be displayed. Select Open with GitHub Desktop:

Figure 2.7 – Cloning from the source path to the local destination

Click Clone; the project will be put in the repos path.

Next, we will change the Local path directory so that it points to where our project lives. We can do this by clicking Choose..., changing the directory to repo\wdio, and clicking Clone:

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 WDIO folder.

Then, click Open Folder, navigate to the repo\wdio folder, and click Open:

Figure 2.9 – Trusting the authors of a project

If this dialogue appears, check the Trust the authors of all files in the parent folder ‘repos’ option and click Yes, I trust the authors.

With that, we have covered the clone installation approach. Next, we will install everything.

If you installed WebdriverIO from an existing project, this is where we continue. We need to build the project before we can run our first test. From the Terminal, type the following:

> 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

Incompatibility could occur if we upgrade all packages blindly. Fortunately, there is the yarn upgrade command, which allows the packages to be upgraded individually:

> 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.

Quick tip

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

Lastly, we can confirm the version of WebdriverIO that is installed with the version flag.

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 – npm run wdio:

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 package.json file.

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?

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 gitignore file:

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.

To tell Git to ignore this project folder, simply create a .gitignore file in the root of the project and enter the node_modules folder name:

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

Once this .gitignore file is saved, we will see the changes reflected in GitHub Desktop with a manageable size of just eight files.

Tip

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 (< and >). 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 main or 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

However, this is just staged on our local Git repo. The final step is to click Push origin, which will push it up to GitHub for our team to pull down:

Figure 2.24 – GitHub Desktop shows that all changes have been committed and suggests pushing any new changes

Congratulations! You have made your first commit to your Git repo. Your team members can now pull your changes to be sure all their tests are running smoothly.

But what if you need to add new functionality that will take a few days to complete?

Branching out

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

When your changes are complete, a pull request will be made to pull your changes into the main branch, and the feature branch may be deleted.

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.