Selenium
To learn how to run Java Selenium scripts in Perfecto, review the following information.
To run a Selenium WebDriver test with Java in Perfecto, you should:
- Be familiar with Selenium
- Have existing tests to work with
- Be a novice user of Perfecto
The setup process involves modifying 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
We provide two versions of the same script to help you understand how you can modify your existing scripts to run them in Perfecto: LocalSelenium.java
and PerfectoSelenium.java
For information on running the final script, see the README.md file included with the sample project.
On this page:
Prerequisites
Before you get started, make sure you have installed the following:
- Java 11
- An IDE of your choice, such as Eclipse or IntelliJ IDEA (consider using IntelliJ IDEA)
- Maven
- Android Studio
- Local Appium Server running at http://127.0.0.1 , port: 4723
-
Eclipse users should also install:
-
IntelliJ IDEA users should also install the Maven plugin for IDEA
IntelliJ IDEA versions 7 and later include the TestNG plugin as a built-in plugin.
Optional installations
For source control management, you can install git.
1 | Get started
As a starting point, we will look at LocalSelenium.java
. This is an example of a simple Selenium script that opens the www.perfecto.io website and verifies the title on the page.
The pom.xml
file in the PerfectoSampleProject contains many additional dependencies. Your project pom.xml
file may look different.
To run the sample project:
- Access the sample project in GitHub: https://github.com/PerfectoMobileSA/PerfectoJavaSample
- Clone the project locally, to the location of your choice, or download the project as a ZIP file (in this case, you need to extract the .zip file before using the project).
- Open the project in the IDE of your choice (for example, IntelliJ Idea).
- Run the
LocalSelenium.java
test as TestNG Test.
2 | Configure the script for Perfecto
In this step, we will look into the changes that you need to perform to be able to run the same test on Perfecto.
You will need to update the pom.xml
file with the Perfecto dependencies and add security information, the Perfecto cloud name, driver details, Smart Reporting information, and test data. The updated script example is called PerfectoSelenium.java
. You can find it in the same sample project that we downloaded in 1 | Get started.
The following procedure walks you through the configuration.
Expand a step to view its content.
For the Perfecto integration, copy the dependencies in the pom.xml
file and paste them into the pom.xml
file of your own project. Make sure to replace the variable ${reportium-sdk.version}
with the latest version number of the corresponding dependency.
<dependency>
<groupId>com.perfectomobile</groupId>
<artifactId>pm-webdriver</artifactId>
<version>RELEASE</version>
</dependency>
<dependency>
<groupId>com.perfectomobile</groupId>
<artifactId>http-client</artifactId>
<version>RELEASE</version>
</dependency>
<dependency>
<groupId>com.perfecto.reporting-sdk</groupId>
<artifactId>reportium-java</artifactId>
<version>${reportium-sdk.version}</version>
</dependency>
<dependency>
<groupId>com.perfecto.reporting-sdk</groupId>
<artifactId>reportium-testng</artifactId>
<version>${reportium-sdk.version}</version>
</dependency>
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.
-
Generate your security token through the Perfecto UI. For more info, see Generate security tokens.
-
In
PerfectoSelenium.java
, search for the following line and replace<<security token>>
with your own Perfecto security token:CopyString 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 only included the platformName
capability (which specifies the device operating system), as shown in the following code snippet. For more information, see Define capabilities and Use capabilities to select a device.
DesiredCapabilities capabilities = new DesiredCapabilities(browserName, "", Platform.ANY);
...
capabilities.setCapability("platformName", "Android");
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.
- On the Perfecto landing page, under Manual Testing, click Open Device.
- In the Manual Testing view, do the following to generate capabilities:
- In the list or tile view, click a device.
- In the details pane on the right, click the Capabilities tab.
(Mobile device only) Depending on what you want to see in your code sample, select Device attributes or Device ID.
- From the drop-down list, select the programming language to use.
- The code snippet is updated automatically.
- Click Copy to clipboard.
- 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. 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 PerfectoSelenium.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:
"https://" + Utils.fetchCloudName(cloudName) + ".perfectomobile.com/nexperience/perfectomobile/wd/hub"
Here is the respective line from our sample script:
RemoteWebDriver driver = new RemoteWebDriver(new URL("https://" + Utils.fetchCloudName(cloudName) + ".perfectomobile.com/nexperience/perfectomobile/wd/hub"), capabilities);
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
class to 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.
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 above code snippet. -
CI job information: Job information is used to add your test runs to the CI Dashboard view. Use the
withJob()
method of thePerfectoExecutionContext
instance, supplying the job name and job number, when creating theReportiumClient
instance.
Our sample script uses system variables to fetch thereportium-job-name
and thereportium-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 thereportium-job-name
and thereportium-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 reportium code.
reportiumClient = Utils.setReportiumClient(driver, reportiumClient); //Creates reportiumClient
reportiumClient.testStart("Perfecto mobile web test", new TestContext("tag2", "tag3"));
//Starts the reportium test
reportiumClient.stepStart("browser navigate to perfecto"); //Starts a reportium step
driver.get("https://www.perfecto.io");
reportiumClient.stepEnd();
reportiumClient.stepStart("Verify title");
String aTitle = driver.getTitle();
Utils.assertTitle(aTitle, reportiumClient); //compare the actual title with the expected title
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 in an @AfterMethod
.
@AfterMethod
public void afterMethod(ITestResult result) {
//STOP TEST
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 DigitalZoom Report
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.
-
Right-click the
pom.xml
file and select Run As > Maven build. -
In the Edit Configuration dialog box, on the Main tab:
The first time you run this test, you need to edit the run configuration.
To run this test for the first time:
-
From the Run menu, select Run.
-
Select Edit Configurations.
-
Select the plus sign and select Maven.
- In the Run dialog box, do the following:
- In the Name field, enter a descriptive name for the run.
- On the Parameters tab, in the Command line field, enter the following command, depending on whether credentials are hard-coded or passed as parameters.
-
Click Run.
The following image shows sample run results.
To perform subsequent runs:
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.
- From the Run menu, select Run > <Name>.
Also in this section