Appium

This section provides instructions on how to run Appium Driver tests with Java in Perfecto.

To learn about Appium 2, including how to use an Appium 2-compliant client with Perfecto, see also our free Appium 2.0: Fundamentals course on BlazeMeter University. To register for this course, you must be logged in. For upgrade information, see Upgrade to an Appium 2-compliant client.

How to run your Java Appium script in Perfecto

This section assumes that you:

  • Are familiar with Appium
  • Have existing tests to work with
  • Are a novice user of Perfecto

To run your tests in Perfecto, you need to modify your existing scripts to include:

  • What driver you want to use
  • Where your Perfecto instance is located 
  • Who you are
  • What devices you want to work on

Prerequisites

Before you get started, make sure you have installed the following:

Appium limitations

Perfecto is aligned with Appium and, therefore, does not support using the clipboard for copy-paste operations on real devices.

For reference, see the Appium information for the custom command extensions mobile: setPastboard and mobile: getPastboard.

1 | Get started

  1. Access the sample project in GitHub and copy the clone URL: https://github.com/PerfectoMobileSA/PerfectoJavaSample
  2. Open your IDE and check out the project from GitHub.

2 | Configure the script for Perfecto

In this step, we update the pom.xml file with the required Perfecto dependencies and modify the script from Step 1 to add in security information, the Perfecto cloud name, Smart Reporting information, and test data. We also want to make sure that the script exits gracefully.

The updated script is called PerfectoAppium.java. The following procedure walks you through the configuration.

The script uses a sample application that is in the lib of the project:

You can choose to skip this and immediately start using your own application by adding the application manually to your repository and then referencing it in the code.

Note:

If you choose to use your own application, these pre-written steps will not work. Instead, we will just check that your app is launching. This will serve as a verification for the entire setup.

Expand a step to view its content.

Copy the dependencies in the pom.xml file and paste them into the pom.xml file of your own project. This step is essential because the imports in our final script only work when the dependencies specified in this file are available.

Generate your security token through the Perfecto UI.

  1. In the Perfecto UI at <YourCloud>.app.perfectomobile.com (where YourCloud is your actual cloud name, such as mobilecloud), click your user name and select My security token. 

  2. In the My security token form, click Generate Security Token.

  3. Click Copy to clipboard. Then paste it into any scripts that you want to run with Perfecto. 

  4. Click Close.

Then search for the following line in PerfectoAppium.java and replace <<security token>> with your Perfecto security token. 

Copy 
String securityToken = "<<security token>>";

Alternatively, you can pass the token as a Maven property, as follows:

Copy 
-DsecurityToken=<<SECURITY TOKEN>>

Use capabilities to select a device from the Perfecto lab. You can be as generic or specific as needed. In our script, we have included the these capabilities, as shown in the following code snippet:

  • model: The device model
  • openDeviceTimeout: The timeout, in minutes, to wait for a specific device in case it is not available at the start of the script (use with caution)
  • appPackage: The Java package of the Android app you want to run

For more information on capabilities, see:

Copy 
DesiredCapabilities capabilities = new DesiredCapabilities(browserName, "", Platform.ANY);
...    
capabilities.setCapability("model", "Galaxy.*");
capabilities.setCapability("openDeviceTimeout", 2);
capabilities.setCapability("appPackage", "com.android.settings");
capabilities.setCapability("appActivity", "com.android.settings.Settings");

You can use the Manual Testing view in the Perfecto UI to generate a code snippet with device-specific capabilities that you can then copy-paste into your script. 

  1. On the Perfecto landing page, under Manual Testing, click Open Device.
  2. In the Manual Testing view, do the following to generate capabilities:
    1. In the list or tile view, click a device.
    2. In the details pane on the right, click the Capabilities tab.

    3. (Mobile device only) Depending on what you want to see in your code sample, select Device attributes or Device ID.

    4. From the drop-down list, select the programming language to use.
    5. The code snippet is updated automatically.
    6. Click Copy to clipboard.
    7. Paste it into your existing script.

As part of creating an instance of the RemoteWebDriver, you need to supply the URL of your Perfecto cloud. Search for the following line in PerfectoAppium.java and replace <<cloud name>> with the name of your Perfecto cloud (for example demo).

String cloudName = "<<cloud name>>";

The general structure of the URL string is as follows:

Copy 
"https://" + Utils.fetchCloudName(cloudName) + ".perfectomobile.com/nexperience/perfectomobile/wd/hub"

Here is the respective line from our sample script:

Copy 
driver = new AndroidDriver<>(new URL("http://127.0.0.1:4723/wd/hub"), capabilities);
Note:

If the URL for your cloud has the structure https://<cloudName>.app.perfectomobile.com, omit .app and enter the URL as follows: https://<cloudName>.perfectomobile.com/nexperience/perfectomobile/wd/hub

To get the most out of running your test in Perfecto , you need to create an instance of the Smart Reporting client (ReportiumClient). This will allow you to later retrieve and analyze the test report. The reporting client is responsible for gathering basic information about the test and transmitting it to the Smart Reporting system.

In Utils.java, we show how to use the ReportiumClientFactory class' createPerfectoReportiumClient() method. Use the PerfectoExecutionContext classto supply the link to the factory class creating the client instance. Use the withWebDriver() method to supply the link of the driver instance.

Use the build() method to create the context object's instance and supply this to the createPerfectoReportiumClient() method when creating the ReportiumClient instance.

Copy 
PerfectoExecutionContext perfectoExecutionContext;
if(System.getProperty("reportium-job-name") != null) {
        perfectoExecutionContext = new PerfectoExecutionContext.PerfectoExecutionContextBuilder()
                .withProject(new Project("My Project", "1.0"))
                .withJob(new Job(System.getProperty("reportium-job-name") , Integer.parseInt(System.getProperty("reportium-job-number"))))
                .withContextTags("tag1")
                .withWebDriver(driver)
                .build();
} else {
        perfectoExecutionContext = new PerfectoExecutionContext.PerfectoExecutionContextBuilder()
                .withProject(new Project("My Project", "1.0"))
                .withContextTags("tag1")
                .withWebDriver(driver)
                .build();
}
ReportiumClient reportiumClient = new ReportiumClientFactory().createPerfectoReportiumClient(perfectoExecutionContext);

In addition to supplying the driver link, the context supports optional settings, such as adding:

  • Reporting tags: Tags are used as a freestyle text for filtering the reports in the Reporting app. Use the withContextTags() method as shown in the following code snippet.

  • CI job information: Job information is used to add your test runs to the CI Dashboard view. Use the withJob() method of the PerfectoExecutionContext instance, supplying the job name and job number, when creating the ReportiumClient instance.
    Our sample script uses system variables to fetch the reportium-job-name and the reportium-job-number values . Both system variables are sent from CI tools like Jenkins as a Maven -D system property. For example:

    -Dreportium-job-name=${JOB_NAME} -Dreportium-job-number=${BUILD_NUMBER}

    The following figure illustrates how the reportium-job-name and the reportium-job-number system variables get their value from Jenkins. These variables are passed as -D parameters for install goals of Maven.

    Our script supports both local and CI-based executions (for more information, see Add reporting to Jenkins > Supply Maven or Ivy parameters).

Replace the existing code after the try block with the following settings app code.

Copy

Settings app code

reportiumClient = Utils.setReportiumClient(driver, reportiumClient); //Creates reportiumClient
reportiumClient.testStart("My Settings Test", new TestContext("tag2", "tag3")); //Starts the reportium test

reportiumClient.stepStart("Verify Settings App is loaded"); //Starts a reportium step
driver.findElement(By.xpath("//*[contains(@resource-id,':id/collpasing_app_bar_extended_title') or contains(@resource-id,'settings:id/search')] | //*[contains(@text,'Search')]")).isDisplayed();
reportiumClient.stepEnd(); //Stops a reportium step

reportiumClient.stepStart("Verify Airplane mode is displayed");
WebElement data = driver.findElement(By.xpath("//*[contains(@text,'Airplane mode')]"));
Utils.assertContainsText(data, reportiumClient, "Airplane mode");
reportiumClient.stepEnd();

In our example, the test is separated into logical groupings of actions as logical steps. Each step is labeled and appears in the Execution Report together with the component actions. The beginning of each logical step is indicated with the stepStart() method, providing the label of the step, and the end of each logical step with the stepEnd() method (for the report).

To close Smart Reporting and the driver, supply an indication of the final outcome of the test by generating a TestResult instance in an @AfterMethod.

Copy 
@AfterMethod
public void afterMethod(ITestResult result) {
            TestResult testResult = null;
            if(result.getStatus() == result.SUCCESS) {
                  testResult = TestResultFactory.createSuccess();
            }
            else if (result.getStatus() == result.FAILURE) {
                  testResult = TestResultFactory.createFailure(result.getThrowable());
            }
            reportiumClient.testStop(testResult);

            driver.close();
            driver.quit();
            // Retrieve the URL to the report in Perfecto Smart Reporting 
            String reportURL = reportiumClient.getReportUrl();
            System.out.println(reportURL);
}

In our example, the createSuccess method notifies the reporting server that the test resulted in a successful status. The createFailure method notifies the reporting server that the test resulted in an unsuccessful status and supports adding a notification message that is displayed in the test report. Our script also provides a failure reason, but this is optional. To learn more about failure reasons in reporting, see Work with failure reasons.

Last, make sure to close and quit the RemoteWebDriver and retrieve the Smart Reporting URL for the generated test report.

Now that your script is ready to run, perform the following steps to execute the test.

  1. Right-click the pom.xml file and select Run As > Maven build.

  2. In the Edit Configuration form, on the Main tab:

    1. In the Goals field, enter the following Maven goals:

      • If the credentials are hard coded:

        Copy 
        clean install

      • If the credentials are passed as parameters:

        Copy 
        clean
        install
        -DcloudName=${cloudName}
        -DsecurityToken=${securityToken}
        -DtestngXmlFile=testng_perfecto.xml

    2. Click Run.

      The following image shows sample run results.

The first time you run this test, you need to edit the run configuration. 

To run this test for the first time:

  1. From the Run menu, select Run.

  2. Select Edit Configurations. 

  3. Select the plus sign and select Maven.

  4. In the Run form, do the following:
    1. In the Name field, enter a descriptive name for the run.
    2. On the Parameters tab, in the Command line field, enter the following command, depending on whether credentials are hard-coded or passed as parameters.

      • If credentials are hard-coded:

        Copy
        clean 
        install

      • If credentials are passed as parameters:

        Copy
        clean
        install
        -DcloudName=${cloudName}
        -DsecurityToken=${securityToken}
        -DtestngXmlFile=testng_perfecto.xml

  5. Click Run.

    The following image shows sample run results.

To perform subsequent runs: 

  • From the Run menu, select Run > <Name>. 
Note:

You can pass the TestNG file name as a Maven property to execute specific TestNG files, as follows:

-DtestngXmlFile=<<testng file name>>.xml

testng_perfecto.xml is configured by default, and it is not mandatory to pass it as a Maven property. However, you can override it by passing your preferred TestNG name as a Maven property, such as -DtestingXmlFile=testng.xml, to execute all 4 tests in parallel.

Also in this section