Page tree
Skip to end of metadata
Go to start of metadata

Last updated: Dec 26, 2018 17:45

Important Note: This feature is available under a separate license. For more information on implementing this feature on your Perfecto Lab, contact Perfecto Product Management.

Introduction

To use the functionality described in this document -

  • Download SDK the DigitalZoom Reporting SDK - reportium-java-<version>.jar

  • Download the additional jar file - reportium-import-java-<version>.jar

  • (Optional) Download the additional jar file - reportium-import-selenium-<version>.jar  - that supports Appium/Selenium scripts that will use the event-firing driver described here.

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:

ClassDescription
ReportiumImportClientReporting client for passing test information for tests executed on external server.
ImportExecutionContextProvides the context within which the test report information is generated.
ReportiumImportClientFactoryGenerates the Reporting client instance - based on the reporting server, context (generated by ImportExecutionContext), additional test information.

Note: This SDK extension is supported for SDK version 1.1.19 or later.

Establish Connection

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.
        ImportExecutionContext executionContext = new ImportExecutionContext.Builder().build();
        Connection connection = new Connection(new URI(REPORTIUM_URL), SECURITY_TOKEN);
        ReportiumImportClient reportiumClient = new ReportiumImportClientFactory().createReportiumImportClient(connection, executionContext);

REPORTIUM_URL

Use the following format for the URI of the reporting server: https://<CQL_NAME>.app.perfectomobile.com Where <CQL_NAME> is the name of your Perfecto CQ Lab

The <CQL_NAME>  string will be used to keep the test report information from your company's tests separate from all other test information in a secure repository accessible to your personnel.

SECURITY_TOKEN

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.

Platform information

The SDK includes a Platform class that encapsulates the information regarding the device. The Platform class includes the following information:

FieldValuesDescription
Device TypeMOBILE | BROWSERIdentifies the type of device used, this is an enum value that supports only these values
DeviceDevice instanceInstance of the Device class (see below) that describes the device used. The class comes in two flavors
Platform OSStringOS of the platform - normally Android or iOS or Windows or MacOS
Platform VersionStringVersion of the OS used
Screen ResolutionStringThe screen resolution used for the test

Mobile device information

The MobileInfo class provides the following information related to the mobile device:

FieldValuesDescription
ModelStringModel name of the device, for example Nexus6P, iPhone8
ManufacturerStringMaker of the device, for example LG, Samsung
Device IDStringIdentifier of the device



The following code snippet creates a Platform instance that includes a mobile device:

        MobileInfo mobileInfo = new MobileInfo.Builder()
                .withManufacturer("Samsung")
                .withModel("Galaxy Note 8")
                .withOperator("Sprint")
                .build();

        Platform platform = new Platform.Builder()
                .withMobileInfo(mobileInfo)
                .withOs("Android")
                .withDeviceType(DeviceType.MOBILE)
                .withScreenResolution("1440x2960")
                .build();

Browser device information

The BrowserInfo class provides the following information related to the mobile device:

FieldValuesDescription
BrowserType

CHROME |

FIREFOX |

SAFARI

Type of browser used in the test
VersionStringVersion number of the browser used for the test

The following code snippet creates a Platform instance that includes a browser device:

        BrowserInfo browserInfo = new BrowserInfo.Builder()
                .withBrowserType(BrowserType.CHROME)
                .withBrowserVersion("60")
                .build();

        Platform platform = new Platform.Builder()
                .withBrowserInfo(browserInfo)
                .withOs("Windows")
                .withOsVersion("10")
                .withDeviceType(DeviceType.DESKTOP)
                .withScreenResolution("1366x768")
                .build();

Context parameters

The ImportExecutionContext class supports all test labeling parameters supported by the PerfectoExecutionContext class. These include:

  • Tags
  • Job Number and Name
  • Project information
  • Platform information

The following snippet shows how to set the parameters of the ImportExecutionContext instance:

        ImportExecutionContext executionContext = new ImportExecutionContext.Builder()
                .withJob(new Job("my job name", 123))
                .withProject(new Project("my project name", "ver 123"))
                .withContextTags("tag1", "tag2", "tag3")
                .withPlatforms(platform)
                .build();

        Connection connection = new Connection(new URI(REPORTIUM_URL), SECURITY_TOKEN);
        ReportiumImportClient reportiumClient = new ReportiumImportClientFactory().createReportiumImportClient(connection, executionContext);

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.

Note: The testStop() method of the ReportiumImportClient accepts a list of TextAttachment objects that will be attached to the test report (see below for more details).

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.

        reportiumClient.testStart("my test name", new TestContext("tag4", "tag5"));
        // test initialization code
        reportiumClient.stepStart("my step");
        // add test step code
        reportiumClient.stepEnd();
        // repeat the stepStart and stepEnd as needed
        
        // supply the test result value as part of the testStop
        reportiumClient.testStop(TestResultFactory.createFailure("it was a failure"));

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 -

reportiumClient.setAsyncUpload(false);

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:
// create the RemoteWebDriver instance - or an AppiumDriver flavor
RemoteWebDriver rwdDriver = createWebDriver();
// use the automation driver and the reportium client to create an instance of the Event firing driver.
EventFiringWebDriver perfectoDriver = new PerfectoEventFiringWebDriver(rwdDriver, reportiumClient);

From this point, use the perfectoDriver instance in place of your rwdDriver, for example:

// use the following
perfectoDriver.findElement(...).click();
// in place of any rwdDriver.findElement().click(); command;

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:

// create the Command object that reports execution of a command with its resulting status
		Command command = new Command.Builder()
                .withName("my command name")
                .withMessage("my command message")
                .withStatus(CommandStatus.SUCCESS)
                .addParameter(new CommandParameter("name1", "value1"))
                .addParameter(new CommandParameter("name2", "value2"))
                .build();

        reportiumClient.command(command);

// Add a screenshot previously stored in a file to the command report entry
        File screenshotFile = new File(…);
        Command command = new Command.Builder()
                .withName("my command name")
                .withStatus(CommandStatus.SUCCESS)
                .withStartTime(commandStartTime)
                .withEndTime(commandEndTime)
                .addScreenshotAttachment(new ScreenshotAttachment.Builder()
                        .withAbsolutePath(screenshotFile.getAbsolutePath())
                        .build())
                .build();

        reportiumClient.command(command);

// Add a screenshot taken from the live input stream provided
        InputStream screenshotInputStream = …;
        Command command = new Command.Builder()
                .withName("my command name")
                .withStatus(CommandStatus.SUCCESS)
                .withStartTime(commandStartTime)
                .withEndTime(commandEndTime)
                .addScreenshotAttachment(new ScreenshotAttachment.Builder()
                        .withInputStream(screenshotInputStream)
                        .withContentType(ScreenshotAttachment.IMAGE_JPEG)
                        .build())
                .build();

        reportiumClient.command(command);

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 [see example below], 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:

        String pdfFile = "TestDescription.pdf";
        Attachment pdfAttachment = new Attachment.Builder<>()
                .withType("Test Design")
                .withContentType("application/pdf")
                .withFileName(pdfFile)
                .withExtension(FilenameUtils.getExtension(pdfFile))
                .withZipped(false)
                .build();

        reportiumClient.addArtifacts(pdfAttachment);

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:

  1. Preparing the file's metadata for the reporting server with the TextAttachment's build() method.
  2. 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):

        File xmlFile = new File(<file-path>);
        Attachment xmlAttachment = new TextAttachment.Builder()
                .withAbsolutePath(xmlFile.getAbsolutePath())
                .build(); // no need to pass content type and file name, since we can guess them from the provided path

        InputStream textFileInputStream = new ClassPathResource(<stream-identifier>).getInputStream();
        Attachment txtAttachment = new TextAttachment.Builder()
                .withInputStream(textFileInputStream)
                .withContentType(TextAttachment.TEXT_PLAIN)
                .withFileName("text_file.txt")
                .build();

        reportiumClient.addArtifacts(xmlAttachment, txtAttachment); 

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

reportiumClient.close();

This allows the asynchronous events to complete before closing the test program, which will guarantee that your report includes all test information.

Use the getReportURL method to retrieve the link to the STR.

System.out.println(reportiumClient.getReportUrl());

Code Samples

See the simple code samples in the GitHub Repository.