Last updated: Dec 26, 2018 17:45
To use the functionality described in this document -
Download SDK the DigitalZoom Reporting SDK -
Download the additional jar file -
The Import SDK is an additional Reporting SDK that supports generating DigitalZoom Single Test Reports (STR) for test executions executed on external servers or emulators - not connected to the Perfecto Lab. The basic use of the API exported by the SDK is:
- Establish a connection to the Reporting Server - requires a Security Token.
- Provide basic information regarding the test -
- Description of platform used to run the test.
- Tags, Job description, etc.
- To allow the test report to display the test code - supply the custom fields that identify the script source code.
- Activate the Test Start, End, and Steps in the testing script code. (Use basic SDK API)
- Retrieve the link to the Single Test Report.
Basic Information Units
The SDK defines a small set of classes that provide the interface (detailed below) to perform the process outlined above:
|ReportiumImportClient||Reporting client for passing test information for tests executed on external server.|
|ImportExecutionContext||Provides the context within which the test report information is generated.|
|ReportiumImportClientFactory||Generates the Reporting client instance - based on the reporting server, context (generated by ImportExecutionContext), additional test information.|
To turn any execution into a DigitalZoom report simply pass the information to the Perfecto Reporting server. The test information is stored in a repository on the reporting server.
Establish the connection using the Classes of the SDK. The following code snippet performs the following steps to establish a very basic and simple connection:
- Create a new instance if the context class for the data-import functionality.
- Prepare the connection parameters.
- Create a new instance of the Reportium client - ready to receive the data regarding the external test.
Use the following format for the URI of the reporting server:
Your personal authentication token, provides secure access to the DigitalZoom Reporting Server. To generate the token follow the procedure presented here.
Basic Test Information
When creating the test report for an execution - the STR includes basic information regarding the test. In particular, the report identifies the test with:
- The device/platform test was run on.
- Job name and number that test is part of.
- Tags to be associated with the test.
The SDK includes a Platform class that encapsulates the information regarding the device. The Platform class includes the following information:
|Device Type||MOBILE | BROWSER||Identifies the type of device used, this is an enum value that supports only these values|
|Device||Device instance||Instance of the Device class (see below) that describes the device used. The class comes in two flavors|
|Platform OS||String||OS of the platform - normally Android or iOS or Windows or MacOS|
|Platform Version||String||Version of the OS used|
|Screen Resolution||String||The screen resolution used for the test|
Mobile device information
The MobileInfo class provides the following information related to the mobile device:
|Model||String||Model name of the device, for example Nexus6P, iPhone8|
|Manufacturer||String||Maker of the device, for example LG, Samsung|
|Device ID||String||Identifier of the device|
The following code snippet creates a Platform instance that includes a mobile device:
Browser device information
The BrowserInfo class provides the following information related to the mobile device:
|Type of browser used in the test|
|Version||String||Version number of the browser used for the test|
The following code snippet creates a Platform instance that includes a browser device:
The ImportExecutionContext class supports all test labeling parameters supported by the PerfectoExecutionContext class. These include:
- Job Number and Name
- Project information
- Platform information
The following snippet shows how to set the parameters of the ImportExecutionContext instance:
Adding Test Start, Steps, and Stop
After creating the ReportiumImportClient instance, use the testStart, stepStart, stepEnd, and testStop methods as they are used for the ReportiumClient instance. Supply the test result as part of activating the testStop method.
Your test may be embedded between the steps. Do not pass the driver variable to the ReportiumClient instance, since this is not linked to the Perfecto system.
Collecting Execution Information
Normally, a test step (code between the stepStart and stepEnd methods) includes automation operations whose results should be reported. This SDK for external automation testing offers two options for reporting the operations executed by the script:
- Use a Perfecto extension of the Selenium EventFiringWebDriver class to automatically generate reporting items from each Selenium/Appium operation.
- Use a ReportiumImportClient method to generate entries in the report collector, specifying the actions performed and the results.
By default, the execution information is sent asynchronously to the DigitalZoom reporting server by a background thread, to minimize the overhead on the test execution. If there is a need to have the execution information sent by the foreground test script, use the setAsyncUpload() method of the ReportiumImportClient instance. To turn off the asynchronous event transfer -
Turning off the AsyncUpload feature may affect the execution time of the test script, as each command will transmit an event to the reporting server.
The PerfectoEventFiringWebDriver Class
Perfecto supplies an extension of the Selenium EventFiringWebDriver class that activates the basic automation driver of the script and generates a reporting event for each action and communicates information to the ReportiumImportClient as report units. Using this class, allows the report to be generated together with information regarding any Selenium/Appium actions in a transparent methodology.
To use the PerfectoEventFiringWebDriver class
- add a project dependency on the reportium-import-selenium jar file.
- add the following code to your automation script, after creating the ReportiumImportClient instance:
From this point, use the perfectoDriver instance in place of your rwdDriver, for example:
Using the ReportiumImportClient.command() method
The ReportiumImportClient supports a command() method whereby you can explicitly add information regarding an operation performed by the automation script. This is particularly useful in cases where:
- the automation performs some operations that are not part of Selenium/Appium, for example an internal framework.
- you do not need to report all automation operations, and wish to focus only on a small set of logical operations.
The command() method accepts a Command class instance - configured with all the information to add to the report entry. The Command class supports the following report entry information units:
- Command name (withName method)
- Command status (withStatus method)
- Execution description (withMessage method)
- Start and End times (withStartTime and withEndTime methods)
- Add parameter values (addParameter method)
- Add screenshot artifact (addScreenshotAttachment method)
The following snippets demonstrate the use of this class and the command() method:
Attaching files to test report
If the test script generates or accesses files or streamed information that it is important to attach to the test report, to provide context or additional information in analyzing the results, you can perform this by first creating an Attachment instance, using the Attachment.Builder() method], that provides the vital metadata for the attachment and then using the addArtifacts() method of the ReportiumImportClient instance.
The API supports adding any type of attachment. When creating the Attachment object, simply supply -
- Content Type - the MIME type that best describes how to display the file.
- Type - a string used by the DigitalZoom server to classify the data file. (This is optional for Text or Screenshot attachments.)
- File Name - name of the file to save.
- Supply at least one of the following:
- Input Stream - for streamed data.
- Absolute Path - for non-streamed data, indicates where the data is taken from.
Additional optional information includes:
- Extension - extension of the data file. DigitalZoom will try to determine this if not supplied.
- Zipped - an indication if the attachment is a condensed file. DigitalZoom will determine this if file extension is .zip.
The following shows how to use the Attachment type to attach a generic file attachment:
Special Attachment Types
The DigitalZoom SDK supports two special classes of Attachments:
- Text attachments - use the the dedicated TextAttachment Builder() method
- Screenshot attachments - use the the dedicated ScreenshotAttachment Builder() method (see example above)
If the attachment can be represented as text - regardless of the format, for example JSON, XML, Plain text - you can attach these to the test report for the execution by:
- Preparing the file's metadata for the reporting server with the TextAttachment's build() method.
- Providing the set of TextAttachment instances to the ReportiumImportClient's addArtifacts() method.
The TextAttachment class supports methods to define either a static file's path or a connection to an incoming text stream.(see the following example snippet):
Completing the test script
When using asynchronous reporting events (default, see here) you should add the following command to the script after closing the automation driver (for example RemoteWebDriver, ChromeDriver, or AppiumDriver):
This allows the asynchronous events to complete before closing the test program, which will guarantee that your report includes all test information.
Retrieve the Report's Link
Use the getReportURL method to retrieve the link to the STR.
See the simple code samples in the GitHub Repository.