Report customization | Ranorex
HomeUser GuideRanorex Studio FundamentalsReportingReport customization

Report customization

Ranorex provides various options for customizing standard reports. This chapter introduces and explains the basic concept of reporting and the possibility to change the layout and the content of Ranorex standard reports.
In this chapter

    Sample solution

    The herein introduced concepts of report customization are explained along with a practical example. This example can be downloaded here.

    Training! What do I do?

    Theme: Report customization Time: Less than 30min Download sample file

    Installation:

    1. Unzip the project directory to any folder on your computer
    2. Start Ranorex Studio and open the solution file Introduction.rxsln

    Structure & concept of reporting

    The concept of Ranorex reports is simple and displayed in overview in the below image.
    Concept of Ranorex reporting

    Concept of Ranorex reporting

    Important to know:
    • The report engine of Ranorex collects test data and converts them into an HTML-file format
    • Ranorex Studio implements an HTML-viewer and displays the report
    • The report engine creates an HTML-report file format based on CSS and XSL specifications

    Collected test data

    Test data are collected and stored in an XML-file format. Test data are readable and can easily be used outside of Ranorex, too.
    Test data in XML-file format

    Test data in XML-file format

    Important to know:
    • Test data are stored in XML format
    • The XML-test data file has the same file name as the corresponding final HTML-report file with the file suffix ‘.data

    Collected test data

    Test data are collected and stored in an XML-file format. Test data are readable and can easily be used outside of Ranorex, too.
    Report file and test data file

    Report file and test data file

    CSS & XSL specification

    The HTML file generation is based upon the common concepts of CSS and XSL specification.
    Concepts of XSL and CSS processing

    Concepts of XSL and CSS processing

    Important to know: XSL and CSL files are stored in the reports folder in the test solution file structure.
    CSS and XSL specification files

    CSS and XSL specification files

    Further reading

    To be able to change the layout and content of Ranorex standard reports, a basic understanding of HTML, CSS, XSL, and XML is recommended. Refer to the World Wide Web Consortium (W3C) at www.w3.org for further reading.

    HTML report file

    The final test report is stored in HTML-file format in the reports folder of the test solutions file directory.
    HTML-report file and displayed report in Ranorex Studio

    HTML-report file and displayed report in Ranorex Studio

    Important to know:
    • The report can be viewed with any common HTML-browser
    • The HTML-report file can be edited with any available HTML-editor

    Creating a custom report template

    After introducing the basic concept of Ranorex reporting, we here explain how to customize Ranorex standard reports. Ranorex provides a convenient way of report customization without destroying the default report mechanisms.
    Creating a custom report template

    Creating a custom report template

    Open the context menu in test suite view and click Properties
    Change to the Report register tab of the properties window
    Click Create custom template and wait for the finish info message box
    Confirm with OK

    Result(s):

    • See the project file view for the new custom report file structure
    NewCustomTemplate1 in project file view

    NewCustomTemplate1 in project file view

    CSS, XSL and image files
    • Ranorex prepares a copy of the XSL and CSS files. These are the custom files to be changed to customize layout and content of the report
    • The ‘.png’ file contains the Ranorex logo as default logo for the test report and other graphical images used within the standard report. The contents of this file can be replaced by customized information.
    Test view files
    • Ranorex prepares a test data file and a generated test report file for quick result check
    • These files can be used to quickly check and review the customization results without the need to start Ranorex Studio

    Multiple custom report templates

    It is possible to create multiple custom report templates. But it is important to note, that only one custom report template is valid for the corresponding test suite. Create as many custom report templates as you need and proceed as explained in the previous section.
    Example for two custom report templates created

    Example for two custom report templates created

    Result(s):

    • See the created custom report templates in the project file structure

    Applying one custom report template

    If there are prepared customized report templates, or if a custom report template folder has been renamed, there is the need of applying the one to be valid.
    Note icon

    Note

    Only one custom report template can be valid for a test suite.
    Change to test suite view and select the test suite
    Open the context menu and click Properties
    Change to the Report register tab of the properties
    Applying a custom report template

    Applying a custom report template

    Click Choose custom template…
    Select the custom report templat to apply
    Confirm with OK

    Resetting to default report template

    You can – at any time – reset to the default Ranorex report template.
    Change to test suite view of your test project
    Select the test suite and open the context menu
    Select the local properties of the test solution
    Change to the ‘Report’ tab folder in the properties window
    Resetting to default report template

    Resetting to default report template

     Click Reset to default and confirm with OK

    Result(s):

    • Resetting to default test report does not delete any customized report templates
    • Customized report templates can be assigned easily by applying it as described in the previous section
    Ranorex standard report template

    Ranorex standard report template

    Renaming custom report templates

    Custom report templates can be renamed at the user’s will. Follow the instructions herein.
    Renaming a custom report template

    Renaming a custom report template

    Select the custom report template in the project file view
    Rename the custom report template folder
    See the renamed folder in the project file view
    tipp icon

    Attention

    • The Ranorex report engine does not automatically recognize the name change of the custom report template
    • Therefore, it is necessary to repeat the application of the renamed custom report template
    Error due to non-application of renamed custom report template

    Error due to non-application of renamed custom report template

    Custom report processing mechanism

    Ranorex implements a special mechanism for processing customized report templates. The understanding of this mechanism is important when changing the layout and/or content of CSS and XSL files of the custom report templates.

    Ranorex output folder /bin/Debug/

    Basically, Ranorex copies all files needed for a test run into a designated output folder /bin/Debug/ of the project folder structure. This includes all report files.
    Ranorex output folder

    Ranorex output folder

    Customized report template folder (‘FrogConsulting’ in this example)
    Report files (.rxlog) and test data files (.rxlog.data)
    CSS and XSL specification files and additional custom report files (i.e. RanorexReport.png = logo file)
    Note icon

    Note

    Ranorex collects and preserves all the files of this output folder with every test run.

    Reports folder /Reports/

    For the sake of improved readability and efficient management and change, Ranorex also manages a report folder where all report files are collected at hand.
    Ranorex reports folder

    Ranorex reports folder

    Collection of all report files (.rxlog) and all corresponding test data files (.rxlog.data)
    CSS and XSL specification files and additional custom report files (i.e. RanorexReport.png = logo file)

    Preserving newest report

    Ranorex updates the report related files at every test run. The below-displayed image shows how this is done.
    Preserving the newest report

    Preserving the newest report

    If a customized report template is applied to the test suite, all affected report files (CSS, XSL, and necessary custom files) are copied from this template folder to the Ranorex /Reports/ folder.
    The /Reports/ folder and the output folder /bin/Debug/ are synchronized at every test run. Therefore, the output folder contains the newest files from the /Reports/ folder.
    tipp icon

    Hint

    To avoid that the styles of old reports get “overwritten” use zipped reports.

    Preparing custom files for preservation

    By default, Ranorex only includes CSS, XSL and automatically generated report files in the preservation process. All necessary custom files (i.e. individual logo files, graphics files, …) need to be included in the process to ensure their participation in the preservation process.
    Copy the custom file(s) needed for reporting into the custom report template folder
    ‘Refresh’ button in project file view toolbar

    ‘Refresh’ button in project file view toolbar

     You initially will not see this copied file within the project file view of Ranorex Studio. Therefore, click Refresh within the project file view toolbar to make it visible
    Including custom file(s) into project

    Including custom file(s) into project

    Any file(s) copied into the custom report folder are initially not part of the project, i.e. they are not included into project processes like preservation and/or updating (see ‘inactivity’ indicator = grey image)
    To include a custom file into the project, select the file and open the context menu
    Click Include in project
    See included custom file(s)
    Important to know:
    • To specify the preservation context of a custom file, open the properties pane by clicking F4
    File property pane with preservation setting

    File property pane with preservation setting

    ‘Never’ is the default setting for any new included custom file
    ‘Always’ is the selection for copying a custom file independent from its preservation status
    ‘Preserve newest’ only copies the newest version of a file

    Layout & logo customization

    In a first example, we show you how to change the basic layout (i.e. colors) of the report and how to exchange the Ranorex logo by a custom specific logo (i.e. your company logo)

    Logo preparation

    If you want to place your individual logo instead of the Ranorex logo into the test report, some graphical preparations may be needed. For explanation purposes, we have prepared a sample logo.
    Prepared sample logo

    Prepared sample logo

    Important to know:
    • The size of the logo is not fixed, you may be able to experiment with different sizes and resolutions
    • It is helpful to know the applied colors, font types, …
    • The current example uses a green background color with the HEX value #ACDB6B
    Result(s):
    • Find the prepared logo in the custom report template folder of the example
    Prepared logo in the custom report template

    Prepared logo in the custom report template

    Exchange report logo

    Exchanging the logo is done in the CSS specification file.
    Exchanging report logo

    Exchanging report logo

    Double-click the CSS specification file to open it
    See the opened CSS specification file
    Insert customized CSS specification

    Insert customized CSS specification

    Move to the end of the CSS specification and find the prepared customization area
    Uncomment the section and replace its contents as follows:
    Background customization
    • The background color is set to the same ‘green’ value as the logo background color
    • All other settings left untouched
    Custom logo
    • Height and width of the logo are set to their respective values (see logo size)
    • Name of logo ‘frogconsulting.png’ is replacing the default logo name
    • Other settings left untouched
    Report info box alignment
    • Finally, there is a top-margin of 40px defined on the report information box to bring some distance between the logo and the below-placed information box
    Result(s):
    • The resulting report should somehow look like:
    Example custom report layout

    Example custom report layout

    tipp icon

    Hint

    If the logo is missing in your customization, remember to include the logo file in the preservation process as explained previously in this section.

    Replacing machine name with username

    There are also various options for changing the contents of the report. Three examples introduce the basic principle and may help you to customize reports according to your own ideas. Assume, that you want the report to show the user’s name instead of the computer/endpoint name. Here is how to do this.

    Important to know:

    • The link between displayed computer/endpoint name in the report and the test data is the XSL specification
    Replacing machine name with username

    Replacing machine name with username

    The headline for computer/endpoint is defined in the XSL specification file
    The host information for the computer/endpoint is found in the test data file
    Within the XSL specification we find the selection command for getting the computer/endpoint name out of the test data file and placing it in the report
    Report username customization

    Report username customization

    Replace ‘Computer/endpoint’ in the XSL specification with ‘Frog user
    Replace the selection of the host variable with the user variable in order to read the test username into the report
    Result(s):
    • The resulting report should somehow look like:
    Report with customized username

    Report with customized username

    Highlighting action report

    Here, we want to show you how to change specific action types within the test report. See the standard test report where a ‘Success’ test action is printed in green font per default. Assume, that we want a successful test validation action to be printed in a ‘bold blue’ font.
    Default font color green of successful test validation message in report
    Default successful test validation report message

    Default successful test validation report message

    Open the CSS specification file by double-click from the project file view
    Search for the color definition of the success report messages
    Changing font-color of test validation message

    Changing font-color of test validation message

    Default font color definition of successful test validation in CSS specification
    Overriding, new font color definition for successful test validation message in CSS specification
    Note icon

    Note

    It is important to leave the initial specification untouched (CSS lines #197 – #199), but add a modified, overriding new specification at the end of the CSS file (CSS lines #1,532 – #1,535) where customizations are recommended.

    Result(s):

    • The resulting report should somehow look like:
    Changed report with newly formatted test validation message

    Changed report with newly formatted test validation message

    Removing information from a standard report

    Assume that the time information within the standard test report is not of importance for us. Therefore, it might be useful to delete this information from the default report. Here is how to do this.
    Non-necessary standard report information

    Non-necessary standard report information

    Double-click the CSS specification file to open it
    Search for occurences of ‘Time’ in the specification
    CSS default specification for table row time information

    CSS default specification for table row time information

    Time column definition
    • There are four (4) specification lines where the ‘Time’ column is defined within the XSL specification
    • All of these need to be ‘deleted’ by simply enclosing them within code comments (<!-- and -->)
    Commenting CSS code
    Time content selection
    • In this specification line, the contents (i.e. the time values of each action line in the report) are read and put into place
    • This section also needs to be commented
    Commenting CSS code

    Result(s):

    • The resulting report should somehow look like:
    Custom report with missing time information

    Custom report with missing time information