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

The setup instructions for WDIO can be found in theGetting Started section on the officialwebsite (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 followingmain topics:

• WebdriverIO setup
• Building and installing the project dependencies
• Making outfirst commit

Tip

Be sure you are viewing the latest version of WDIO 8.0. Googling questions about WDIO features can lead to support pages ofprior versions.

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

• Custom configuration while answering a seriesof questions
• Cloned from an existing projecton GitHub

For this project, we will show the questions and the selected answers. The second option, cloning the boilerplate project approach, is described in thefollowing section.

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

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

> yarn create wdio .

The WDIO robot will appear, and a list of configuration questions willbe 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 selectedat 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 featuresare added.

Figure 2.4 – Settings

? What type of testing would you like to do? (Usearrow keys)

• > (*) E2E Testing - of Web orMobile Applications
• ( ) Component or Unit Testing - inthe browser
• >https://webdriver.io/docs/component-testing
• ( ) Desktop Testing - ofElectron Applications
• >https://webdriver.io/docs/desktop-testing/electron
• ( ) Desktop Testing - ofMacOS Applications
• >https://webdriver.io/docs/desktop-testing/macos

? Where is your automation backend located? (Usearrow keys)

• > (*) On my localmachine (default)
• ( ) In the cloudusing Experitest
• ( ) In the cloud usingSauce Labs
• ( ) In the cloud using Browserstack or Testingbot or LambdaTest or adifferent service
• ( ) I have my ownSelenium cloud

Today, there are many cloud options, includingExperitest,Sauce Labs,BrowserStack,Testingbot, andLambdaTest. For this book, we will install the automation backend on our local Mac orWindows machine.

Next is the environment type. For these purposes, we willuseWeb:

? Which environment would you like to automate? (Usearrow keys)

• (*) Web - web applications inthe browser
• ( ) Mobile - native, hybrid, and mobile web apps, on Androidor iOS

Then, select the browser(s) wewill be using. Select the default of Chrome. Note that we can addothers 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 alllisted frameworks:

? Which framework do you want to use? (Usearrow keys)

• ( )Mocha (https://mochajs.org/)
• ( ) Mocha withSerenity/JS (https://serenity-js.org/)
• (*)Jasmine (https://jasmine.github.io/)
• ( ) Jasmine withSerenity/JS (https://serenity-js.org/)
• ( )Cucumber (https://cucumber.io/)
• ( ) Cucumber withSerenity/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 aTypescript project:

? Do you want to use a compiler? (Usearrow keys

• ( )Babel (https://babeljs.io/)
• (*)TypeScript (https://www.typescriptlang.org/)
• ( )No!

Question: What is Babel and isit needed?

Babel (https://babeljs.io/) is aJavaScript transpiler. Because JavaScript is implemented differently in differentbrowsers, 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 theTypeScript transpiler.

Question: How to know what features are available in different browsersand versions?

Thecaniuse.com website provides descriptive tables of the different ECMAScript features thatare 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 startupsample script.

? Do you want WebdriverIO to autogenerate sometest 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 andintegration tests.

The following is the default path for the TypeScript sample test cases and should notbe changed:

? Where should be the location of yourspecs 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) replacedwith .ts.

? Do you want to use pageobjects (https://martinfowler.com/bliki/PageObject.html)?

Yes

This sets up a Page Object Model folder structure forour project.

? Where are your page objectslocated? ./test/pageobjects/**/*.ts

Now, we want to configureour reporters.

Which reporter do you wantto 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 aVideo 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 aSlack channel.

? Do you want to add a plugin to yourtest setup?

• ( ) wait-for: utilities that provide functionalities to wait for certain conditions till a defined taskis complete.
• >https://www.npmjs.com/package/wdio-wait-for
• ( ) angular-component-harnesses: support for Angular componenttest harnesses
• >https://www.npmjs.com/package/@badisi/wdio-harness
• ( ) Testing Library: utilities that encourage good testing practices laid downby 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 beleft as-is.

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

? Do you want to add a service to yourtest 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 ofthis book.

The WebdriverIOVisual 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 aspecified version).
• ⬇ Download Chromedriver specific to the given VSCode version.
• 🚀 Enables you to access the VS Code API fromyour 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 testingweb extensions.
• 📔 Bootstraps page objects with locators that match your VSCode version.

The nextquestion 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 websitefor testing.

? What is thebase URL?

http://localhost

This is the base landingpage that our testswill 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 sandboxfor 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 thefinal question.

? Do you want me to run `npminstall` (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 theInstalling and configuring WebdriverIO section if you do not plan to clone from anexisting project.

Because weare 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 equivalentyarn.lock file.

> yarn install

Option 1 – cloning WebdriverIO from a boilerplate project

An alternate way toset up WDIO is to use a preconfiguredWDIO 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 thenecessary components.

For this project, we will fork theJasmine TypeScript Boilerplate projectfrom GitHub:

Figure 2.5 – The Jasmine TypeScript boilerplate project on GitHub

Click thejasmine-boilerplate link. This will allow us to create our own version via theCode button:

Figure 2.6 – Copying the project URL from GitHub

ClickCode. Multiple choices for cloning the project will bedisplayed. SelectOpen withGitHub Desktop:

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

ClickClone; the project will be put in therepos path.

Next, we will change theLocal path directory so that it points to where our project lives. We can do this by clickingChoose..., changing the directory torepo\wdio, andclickingClone:

Figure 2.8 – The project’s Explorer icon in VS Code

Click theExplorer icon in the top-left corner of VS Code and open theWDIO folder.

Then, clickOpen Folder, navigate to therepo\wdio folder, andclickOpen:

Figure 2.9 – Trusting the authors of a project

If thisdialogue appears, check theTrust the authors of all files in the parent folder ‘repos’ option and clickYes, I trustthe authors.

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

If you installedWebdriverIO 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, typethe 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 whichare outdated:

> yarn outdated

The output can be seen in thefollowing 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 beupgraded individually:

> yarn upgrade-interactive

We will see thefollowing output:

Figure 2.11 – Interactive package list for upgrading

This gives us the most flexibility when we’re keeping our project packages upto date.

Quick tip

If you want to clear the Terminal, use cls in Windows or Ctrl + K or clearon 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. Theyarn.lock file will never need tobe 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 thesupporting packages:

Figure 2.12 – WebdriverIO with TypeScript successfully installed

Lastly, we can confirm theversion of WebdriverIOthat is installed with theversion flag.

ForWindows users:

> npx wdio --version

ForMac 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 –npmrun 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 followingyarn command:

> yarn wdio

This results in thefollowing 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 Windowsand Mac:

ForWindows users:

> npx wdio run test/wdio.conf.ts

ForMac users:

> wdio run test/wdio.conf.ts

All the test examples can be found in this book’s GitHubrepository:https://github.com/PacktPublishing/Enhanced-Test-Automation-with-WebdriverIO.

This runs the sample tests with basic output detail to the Terminal window from thespecReporter window:

Figure 2.15 – Pass results shown in the spec report from the sample WDIO test

Now that wehave set up our project, either by answering the initialconfiguration questions or cloning an existing project, we are ready to look at the configurations and filesettings of our new WDIOautomation 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 theREADME.mdfile first.

For any project, theREADME 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 asample test.

Next, open thepackage.json file.

This is where much of theNode.jsconfiguration occurs:

Figure 2.17 – All devDependancies in the wdio project

What is theyarn.lock file?

Theyarn.lock filecontains the full list of required project packages, includingones 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 ofthis. Whew!

Let’s run Yarn Package Manager with theinstall command to get everything loaded and upto date:

> yarn install

This can be seen in thefollowing 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 theGitHub 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 thenode_modules folder should be included in thegitignore 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. Havingnpm create the folder contents on the fly with the most up-to-date versionsis better:

Figure 2.20 – GitHub Desktop indicates over 12,000 files to be committed to the new repo

This is far more files thanwe need.

To tell Git toignore this project folder, simply create a.gitignore file in the root of the project and enter thenode_modulesfolder 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 temporarilyor permanently.

By simply adding and saving the.gitignore file, the list of fileschanges 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 justeight 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 filefor 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 onthe page.

There are tools that IT security uses to detect passwords in repos, but they often only check themain ormaster repos and ignore the laterfeature branches. This, too, is a security risk. Always clean up old branches, as this can be considered asecurity operations center (SOC) II compliance violation, even if the passwords have longsince expired.

We can now add a summary description and optional details. Simply clickCommit to main – all our new files will be committed to our localmain branch:

Figure 2.23 – Adding a comment and details to a local commit

However, this is just stagedon our local Git repo. The final step is to clickPush origin, which will push it up to GitHub for our team topull 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 arerunning smoothly.

But what if you need to add new functionality that will take a few daysto 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 frommain. Your changes will be committed to your branch, and changes frommain will be broughtin 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 themain branch, and thefeature branch maybe deleted.

For this book, the final state of the framework will be in a branch named after this chapter. Themain branch will contain thefinal 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 fromGitHub Desktop.

If you run into issues, check theAppendix 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 theseinitial processes.

In the next chapter, we will explore the files and connections in thewdio config file and look at different ways to debugour code.