WebdriverIO

Learn how to set up WebdriverIO (WDIO) with Perfecto. For more information about this test automation framework, see the WebdriverIO website.

The content on this page was created using version 9 of the WebdriverIO framework, which was the current and stable version at the time. All examples and setup instructions are based on WebdriverIO v9.

Setting up the integration involves the following steps:

• Step 1 | Set up a new WebdriverIO framework

  If you already have a WebdriverIO-based framework, skip this step.

• Step 2 | Integrate the WebdriverIO framework with Perfecto

  This will allow you to run tests on real or virtual devices and browsers in Perfecto's cloud infrastructure.

  To learn more about supported devices and platforms, see Supported platforms.

• Step 3 | Integrate WebdriverIO with Perfecto Smart Reporting

  To learn more about Perfecto Smart Reporting, see Test analysis with Smart Reporting.

Step 1 | Set up a new WebdriverIO framework

If you already have a WebdriverIO-based framework, skip this step.

To set up a new WebdriverIO framework, follow the official WebdriverIO documentation. In particular, refer to the following information:

• System requirements

• NPM version

• New WebdriverIO setup

The following setup steps align with the standard setup steps for the WebdriverIO framework. In steps 5, 6, and 7, you configure information relevant to your Perfecto cloud, such as cloud URL, port number, and server path.

To create a new WDIO framework:

1. Initiate the WebdriverIO setup in a terminal using the official wdio init command.

2. Follow the prompts in the WebdriverIO CLI to set up the project location, name, and so on.

3. When prompted "Where is your automation backend located?", select the following option: I have my own Selenium cloud

   

4. Select the appropriate testing environment. For example:

   When prompted for the environment you would like to automate, enter: Mobile - native, hybrid and mobile web apps, on Android or iOS

   When prompted for the mobile environment you would like to automate, enter: Android - native, hybrid and mobile web apps, tested on emulators and real devices

   The options you select do not affect the option to automate iOS or web mobile.

5. When prompted for the IP or URL of your Selenium standalone or grid server, provide the URL of your Perfecto cloud, as follows:

   Copy

   <PERFECTO_CLOUD_NAME>.perfectomobile.com

   where <PERFECTO_CLOUD_NAME> is the name of your Perfecto cloud. For example, if your cloud name is 'demo,' the URL is: demo.perfectomobile.com.

6. When prompted for the port number, enter the port as 80.

7. When prompted for the path to the browser driver or grid server, provide the server path as follows:

   Copy

   /nexperience/perfectomobile/wd/hub/

   

8. Complete the remaining setup steps.

9. After a successful installation, when prompted whether you want to install Appium server, exit the setup without Appium server installation. Tests executed on Perfecto's mobile devices or browsers do not require a local installation of Appium server.

The WebdriverIO project folder should now have the following structure (depending on the answers you provided during the CLI setup).

Step 2 | Integrate the WebdriverIO framework with Perfecto

Setting up the WebdriverIO framework with Perfecto involves configuring the hostname, port, and path properties and adding Perfecto-specific capabilities.

To integrate the framework with Perfecto:

1. Open the wdio.conf.ts or wdio.conf.js file, either in an IDE of your choice, such as Visual Studio Code, or in a text editor.

2. In the configuration file, do the following:

   1. Locate the following parameters and, if the values are not set, configure them as follows:

      • hostname = <PERFECTO_CLOUD_NAME>.perfectomobile.com

        where <PERFECTO_CLOUD_NAME> is the name of your Perfecto cloud. For example, if your cloud name is 'demo,' the URL is: demo.perfectomobile.com.

      • port = 80

      • path = /nexperience/perfectomobile/wd/hub

   2. Locate and remove the runner parameter. When executing tests in the Perfecto cloud, you do not use this parameter.

3. To execute tests in your Perfecto cloud, set the relevant desired capabilities using perfecto:options.

   To learn more about the available capabilities and how to set them, see the following resources:

   • Supported Appium capabilities

   • Use capabilities to select a device

   • Define capabilities for automation testing

   • Generate capabilities during manual testing

4. Add the securityToken desired capability to the perfecto:options object.

   If you don't have your Perfecto security token at hand, see Generate a security token.

   Tip: As a best practice, consider storing the security token in an environment variable instead of directly including it in the WebdriverIO configuration file.

The following screenshot shows an example of desired capabilities for executing tests on the latest Chrome Windows desktop and a real mobile device.

Step 3 | Integrate WebdriverIO with Perfecto Smart Reporting

For non-Cucumber based WebdriverIO framework implementations, follow the steps in the JavaScript instructions.

For Cucumber-based WebdriverIO framework implementations, Perfecto's Professional Services team maintains a WDIO service called wdio-perfecto.v2-service. This service handles the reporting integration and implements all Perfecto extension functions.

To integrate the WDIO Perfecto v2 Service with an existing or new WebdriverIO framework:

1. In the package.json file, add the WebdriverIO Perfecto v2 service . Check the version history of the wdio-perfecto.v2-service for the latest version of this file.

2. In the WDIO config file, add the WebdriverIO Perfecto v2 service in the services parameter, including the parameters required for Perfecto Smart Reporting.

   The WebdriverIO Perfecto v2 service accepts parameters related to Perfecto Smart Reporting and additional configurations. For example, implementing failure reasons ensures tthat your executions are categorized under primary and secondary failure reasons, providing better insights into the cause of a failure. To learn more about failure reasons, see Work with failure reasons.

   failure_reasons is a JSON object. To learn more, check the sample project in GitHub.

   The following screenshot shows a sample implementation.

   

3. To set reporting-related metadata, configure the following environment variables:

   • JOB_NAME: The name of CI Dashboard job

   • JOB_NUMBER: The number of CI Dashboard job

   • PROJECT_NAME: The name of the project used in Perfecto Smart Reporting

   • PROJECT_VERSION: The version of the project

   • BRANCH_NAME: The name of the branch