Appium

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.

Our sample project uses the PerfectoLabUtils.getSecurityToken() method to securely retrieve the Perfecto security token at runtime. To see this code in context, see PerfectoAppium.java.

In your own project, provide the security token in one of the following ways.

This method looks for the token under the key perfecto.security.token, using the utility class ApplicationPropertiesUtil.

• In an application.properties file (in the project root or classpath):

  Copy

  perfecto.security.token=<<SECURITY TOKEN>>

• As a JVM system property, typically passed via Maven:

  Copy

  mvn test -Dperfecto.security.token=<<SECURITY TOKEN>>

• As an environment variable, if supported by ApplicationPropertiesUtil in the project setup.

For help generating a token, see Generate a 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 capabilities shown in the following code snippet:

• browserName: The name of the browser
• model: The device model
• enableAppiumBehavior: Set to true to ensure compatibility with standard Appium behavior
• 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)
• app: The Perfecto repository path of the app under test
• appPackage: The unique identifier of the Android app you want to run

DesiredCapabilities capabilities = new DesiredCapabilities();
capabilities.setCapability("perfecto:browserName", browserName);
capabilities.setCapability("perfecto:model", "Galaxy S.*|LG.*");
capabilities.setCapability("perfecto:enableAppiumBehavior", true);
capabilities.setCapability("perfecto:openDeviceTimeout", 2);
capabilities.setCapability("perfecto:app", repositoryKey); // Set Perfecto Media repository path of App under test.
capabilities.setCapability("perfecto:appPackage", "io.perfecto.expense.tracker"); // Set the unique identifier of your app

For more information on capabilities, see:

• Define capabilities
• Supported Appium capabilities
• Use capabilities to select a device

As part of creating an instance of the RemoteWebDriver, you need to supply the URL of your Perfecto cloud, for example, demo or yourcompany.

Our sample project uses the String cloudName = PerfectoLabUtils.getPerfectoCloudName(); method to securely retrieve the Perfecto cloud name at runtime. To see this code in context, see PerfectoAppium.java.

In your own project, provide your cloud URL in one of the following ways:

• By adding the following line to your application.properties file. Replace <<CLOUD NAME>> with your actual cloud name.

  Copy

  perfecto.cloud.name=<<CLOUD NAME>>

• If you're running your test using Maven, by adding the following line as a system property. This overrides any value set in application.properties.

  Copy

  mvn test -Dperfecto.cloud.name=demo

Later in the test script, the cloud name is used to build the URL and create the driver, as shown in the following code snippet.

driver = new AndroidDriver(
                new URL("https://" + cloudName + ".perfectomobile.com/nexperience/perfectomobile/wd/hub"),
                capabilities);

This line:

• Constructs the Appium server URL dynamically using the cloud name.

• Creates a new instance of the AndroidDriver, which runs your test on a device in the Perfecto cloud.

For example, if the cloud name is demo, the driver connects to: https://demo.perfectomobile.com/nexperience/perfectomobile/wd/hub

To get the most out of running your test in Perfecto, 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 Perfecto Smart Reporting.

In PerfectoLabUtils.java, the setReportiumClient() constructs a ReportiumClient using RemoteWebDriver and metadata (job, project, tags) from property files. It centralizes the reporting client setup for reuse across tests.

    public static ReportiumClient setReportiumClient(RemoteWebDriver driver, ReportiumClient reportiumClient)
            throws Exception {
        
        // Reporting client. For more details, see
        // https://developers.perfectomobile.com/display/PD/Java

        PerfectoExecutionContextBuilder perfectoExecutionContextBuilder = new PerfectoExecutionContext.PerfectoExecutionContextBuilder();

        String jobName = ApplicationPropertiesUtil.getProperty("reportium.job.name");

        if (null == driver) {
            throw new Exception("Set Report Client : Driver can't be null");
        }

        perfectoExecutionContextBuilder = perfectoExecutionContextBuilder.withWebDriver(driver);

        if (null != jobName) {

            int jobNumber = 0;

            String jobNumberStr = ApplicationPropertiesUtil.getProperty("reportium.job.number");

            if (null == null) {
                jobNumber = Integer.parseInt(jobNumberStr);
            }
            Job jobReference = new Job(jobName, jobNumber);
            perfectoExecutionContextBuilder = perfectoExecutionContextBuilder.withJob(jobReference);
        }

        String projectName = ApplicationPropertiesUtil.getProperty("reportium.project.name");

        if (null != projectName) {

            String projectNumber = ApplicationPropertiesUtil.getProperty("reportium.project.number");

            if (null == projectNumber) {
                projectNumber = "1.0";
            }

            Project project = new Project(projectName, projectNumber);
            perfectoExecutionContextBuilder = perfectoExecutionContextBuilder.withProject(project);
        }

        String tags = ApplicationPropertiesUtil.getProperty("reportium.tags");

        if (tags != null) {
            List<String> tagsList = Arrays.asList(tags.split(","));
            perfectoExecutionContextBuilder = perfectoExecutionContextBuilder.withContextTags(tagsList);
        }

        PerfectoExecutionContext perfectoExecutionContext = perfectoExecutionContextBuilder.build();

        reportiumClient = new ReportiumClientFactory().createPerfectoReportiumClient(perfectoExecutionContext);
        if (reportiumClient == null) {
            throw new Exception("Reportium client not created!");
        }
        
        return reportiumClient;

What you need to do:

1. Ensure the WebDriver instance is not null

   The method throws an exception if the passed RemoteWebDriver driver is null. Call this method after the driver has been initialized.

2. Configure reporting properties

   The method relies on several properties being defined. These must be present in the application.properties file or another supported source (for example, system properties if ApplicationPropertiesUtil is configured to pull from them).

   Supply the following optional properties:

   • reportium.job.name: The name of the job (for example, test suite or build)

   • reportium.job.number: The job/build number (should be an integer)

   • reportium.project.name: The name of the project

   • reportium.project.number: The project version or number

   • reportium.tags: Comma-separated tags (for example, smoke,regression)

     Tags are used as a freestyle text for filtering the reports in the Reporting app.

3. Update the application.properties file to include the relevant information. For example:

   Copy

   reportium.job.name=MyJob
   reportium.job.number=123
   reportium.project.name=MyProject
   reportium.project.number=1.0
   reportium.tags=smoke,regression

   If you don't set these properties, the client is still created, but job/project/tag info will be missing from reports.

Replace the sample test code in the main method with the following code, which demonstrates a login scenario in an Android app using Reportium steps and waits for UI interactions such as entering email, password, and confirming successful login.

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

reportiumClient = PerfectoLabUtils.setReportiumClient(driver, reportiumClient); // Creates reportiumClient
reportiumClient.testStart("Android Java Native Sample", new TestContext("tag2", "tag3")); // Starts the
                                                                                                    // reportium test

reportiumClient.stepStart("Enter email");
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(30));
WebElement email = wait
                .until(ExpectedConditions.elementToBeClickable(driver.findElement(By.id("login_email"))));
email.sendKeys("test@perfecto.com");
reportiumClient.stepEnd();

reportiumClient.stepStart("Enter password");
WebElement password = wait
                .until(ExpectedConditions.elementToBeClickable(driver.findElement(By.id("login_password"))));
password.sendKeys("test123");
reportiumClient.stepEnd();

reportiumClient.stepStart("Click login");
WebElement login = wait
                .until(ExpectedConditions.elementToBeClickable(driver.findElement(By.id("login_login_btn"))));
login.click();
reportiumClient.stepEnd();

reportiumClient.stepStart("Login Successful");
wait.until(ExpectedConditions.elementToBeClickable(driver.findElement(By.id("list_add_btn"))));
reportiumClient.stepEnd();

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.

@AfterMethod
public void afterMethod(ITestResult result) {
    TestResult testResult = null;
    if (result.getStatus() == ITestResult.SUCCESS) {
        testResult = TestResultFactory.createSuccess();
    } else if (result.getStatus() == ITestResult.FAILURE) {
        testResult = TestResultFactory.createFailure(result.getThrowable());
    }
    if(null != reportiumClient) {
        reportiumClient.testStop(testResult);
        // Retrieve the URL to the DigitalZoom Report
        String reportURL = reportiumClient.getReportUrl();
        System.out.println(reportURL);
    }
    
    if(null != driver) {
        driver.quit();
    }
}

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.

Steps for Eclipse

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

2. In the Edit Configuration dialog box, 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.

Steps for IntelliJ

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

Important: testng_perfecto.xml is configured by default. You can pass the TestNG file name as a Maven property to execute specific TestNG files, as follows:

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

This is helpful if you want to execute all 4 tests in parallel.

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 dialog box, 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>.