Customization basics

The standard report is usually appropriate for most scenarios. However, to suit individual needs, it’s fully customizable. Because customization is a large topic, we’ve split it up into two chapters.

In this chapter, you’ll learn about the basics of customization and go through a few examples to customize the look of the report without coding.

Reference

For more complex customizations that involve coding, refer to

Ranorex Studio fundamentals > Reporting > ⇢ Complex customizations.

In this chapter

    tipp icon

    Screencast

    The screencast “Introduction to customizing reports” walks you through the information found in this chapter.

    Watch the screencast now

    Download the sample solution

    The explanations in this chapter are based on a sample solution that you can download below.

    Sample solution

    Theme: Report customization
    Time: 15 minutes

    Download sample file

    Install the sample solution:

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

    tipp icon

    Hint

    The sample solution is available for Ranorex versions 8.0 or higher. You must agree to the automatic solution upgrade for versions 8.2 and higher.

    From raw data to the report

    The image below illustrates the process that prepares raw data to be displayed in an easily readable format in the report.

    Concept of Ranorex reporting

    Concept of Ranorex reporting

    1. During the test run, the report engine collects data in an XML format.
    2. The report engine converts this data to HTML and creates a report file based on CSS and XSL specifications.
    3. Ranorex Studio displays this HTML-based report with its built-in HTML viewer.

    Collected test data

    Data from a test run is collected and stored in an XML format. This raw data can also be read and used outside of Ranorex Studio with any XML viewer/editor.

    Test data in XML-file format

    Test data in XML format

    The raw XML data is always saved in the same folder as the corresponding original report file and has the same file name with the added suffix .data.

    Report file and test data file

    Report file and XML-data file

    CSS and XSL specifications

    The raw XML data is used to create a HTML file based on CSS and XSL specifications.

    Concepts of XSL and CSS processing

    The XSL and CSS specifications used to generate the HTML file are also stored in the same folder as the XML data and the actual report.

    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 report generated from XML by XSL and CSS is stored in a HTML-based format in the Reports folder of the project’s output directory.

    HTML-report file and displayed report in Ranorex Studio

    HTML-based report file and report as displayed in Ranorex Studio

    Note icon

    Note

    • The report can be viewed in any web browser.
    • The report file can be edited in any HTML editor.

    Create a custom report template

    Now that we’ve established how reports are generated, we can start customizing the report. There’s a convenient way to do this in Ranorex Studio without affecting the standard report:

    In the test suite view, right-click the test suite.
    Click Properties.
    Click the Report tab.

    Accessing report settings

    Click Create custom template.
    A message appears, telling you where the new report template folder has been created. Confirm with OK.

    Creating a new report custom template

    Result:

    In the projects view, you can see the new template folder with the copied report files.

    NewCustomTemplate1 in project file view

    NewCustomTemplate1 folder in projects view

    CSS, XSL, and image files

    • These are the copied files that you can edit to the customize layout and content of the report.
    • The PNG file contains the Ranorex logo as default logo for the report as well as other images used in the standard report. You can replace these with your own images.

    Preview files

    • These files enable you to quickly check what your customizations will look like in an actual report. Just open View.rxlog to get a preview.
    • You can also open it from Windows, so you don’t have to start Ranorex Studio.

    Multiple custom report templates

    You can create as many custom report templates as you want. However, only one template can be active at a time for a test suite.

    To create additional custom templates:

    Click Reset to default in the Report tab of the test suite properties.
    Click Create custom template again and confirm with OK.

    Creating multiple custom report templates

    Result:

    Another template folder appears in the projects view.

    Example for multiple custom report templates

    Example for multiple custom report templates

    Rename custom report templates

    You can rename custom report templates.

    In the projects view, select the template you want to rename.

    Press F2 and rename the template folder.

    The renamed folder.

    tipp icon

    Attention

    The report engine doesn’t automatically recognize the name change. You will have to reapply the template after renaming it. This is explained in the next section.

    Renaming a custom report template

    Renaming a custom report template

    Error due to non-application of renamed custom report template

    Error if the template isn’t reapplied.

    Choose/reapply a custom report template

    This function is used for three different purposes:

    • To add an existing custom template from a folder.
    • If you have multiple custom templates, to choose which one should be used.
    • If you’ve renamed a template, to reapply it so Ranorex Studio can find it again.
    Note icon

    Note

    Only one custom report template can be active at a time for a test suite.

    Open the Report tab in the test suite properties.
    If there’s a custom template currently active, click Reset to default template.

    Applying a custom report template

    Click Choose custom template….
    Choose a custom template in the browser window.
    Click OK.

    Reset to default report template

    If you want to stop using a custom template, you can reset to the default Ranorex Studio template at any time.

    Open the Reports tab in the test suite properties.

    Click Reset to default and confirm with OK.

    Resetting to default report template
    Note icon

    Note

    Custom report templates won’t be deleted by this action. You can still reapply them as described in the section above.

    Ranorex standard report template

    Ranorex standard report template

    How Ranorex Studio processes custom templates

    Ranorex Studio has a special mechanism for processing customized report templates, which includes the output folder and the reports folder for each project. Understanding this process is important when you want to include external files in a report template, e.g. a PNG containing your logo, because these files aren’t included in the process by default.

    Output folder binDebug

    When you execute a test, Ranorex Studio copies all files needed for the test run into a designated output folder called binDebug, which is located in your project’s folder. This includes the standard files created as part of a custom report template, but excludes external files, such as a logo. External files are copied to the output folder only if they are configured to be and therefore won’t appear in your report by default. How to do this is explained in the next section.

    Ranorex output folder

    Copy of the customized report template folder (FrogConsulting in this example) in the output folder

    Reports folder in the output folder

    Report file (.rxlog) and corresponding raw data file (.rxlog.data)

    CSS and XSL specification files and default logo file RanorexReport.png

    Note icon

    Note

    Ranorex Studio synchronizes all the files of the output folder for every subsequent test run.

    Process summary

    The image and descriptions below illustrate the process. As mentioned earlier, external files need special configuration to be included in the process. In this case, we assume that this has been done. You can learn how to do so further below.

    Preserving the newest report

    A custom report template has been applied to the test suite. The folder for the custom template is located in your project’s folder, FrogConsulting in this example.

    On the first test run, the custom template folder is copied directly to the output folder of the project.

    The report layout files (CSS, XSL, and custom files) are also copied from the template folder directly to the Reports folder in the output folder of the project.

    On subsequent runs, the custom template folders in the project folder and the output folder are synchronized, i.e. the output folder always contains the newest files from the custom template folder.

    Including external files in the report

    By default, Ranorex Studio includes internal files (.rxlog, rxlog.data, .css, .xsl, .png, images, videos) in the reporting process, i.e. only these are copied to the output folder. For external files such as logos to show up in your custom report, you will need to include them in this process manually.

    Copy the external file(s) to the folder of the custom report template you want them to be part of.

    In the projects view in Ranorex Studio, click the refresh button to see the file in the template’s folder.

    ‘Refresh’ button in project file view toolbar

    Right-click the external file.

    Click Include in project.

    The file is now included in the project, but we’re not finished yet.

    Including custom file(s) into project

    Any file(s) copied into the custom report folder are initially not part of the project, meaning they aren’t included in the reporting process either. They appear grayed out in the projects view.

    Select the external file and press F4 to open its properties.

    You can see Copy to output folder is set to Never, so the file would be excluded from the reporting process. Change it to Always or Preserve newest.

    File property pane with preservation setting

    Never is the default setting for any newly included external files.

    Always means the file will be copied to the output folder for each test run.

    Preserve newest means the file will only be copied if the version in the Reports folder is newer than the already existing one in the output folder. If no file exists yet in the output folder, it will always be copied.

    Background color and logo customization

    In this example, you’ll change the background color of the report and replace the Ranorex logo with a custom one. The example is based on the sample solution that’s available for download at the beginning of this chapter.

    The logo

    • Your logo doesn’t have to be a specific size. Experiment with different dimensions.
    • It’s good to know the exact HEX values of the color(s) used in your logo.

    We’ve prepared a sample logo. The green background has the HEX value #ACDB6B.

    Prepared sample logo

    The sample logo is already in the FrogConsulting custom report template folder.

    Prepared logo in the custom report template

    Replace the logo

    To replace the logo, you’ll need to make changes to the CSS specification file.

    In the projects view, double-click the CSS specification file.

    It opens in a new tab.

    Exchanging report logo

    Go to the end of the file and find the customization area.

    Delete this line to uncomment the customization section and then replace its contents as described below.

    Insert customized CSS specification

    Background customization

    • The background color is set to the same green HEX value as the logo background color.
    • All other settings are unchanged.

    Custom logo

    • Height and width of the logo are set to their respective values (see logo size).
    • The default logo name is replaced with “frogconsulting.png”.
    • The other settings are unchanged.

    Report info box alignment

    • Finally, a top margin of 40px is set for the general information box.

    Result:

    Example custom report layout
    tipp icon

    Hint

    If the logo is missing in your report, remember to include the logo file in the project and the reporting process as explained further above.

    Replace Computer/Endpoint with username

    There are also various options for changing the contents of the report. We’ll go through three examples that will introduce the basic principle and help you customize reports according to your own ideas. In the first example, you’ll customize the report so that the entry for “Computer/Endpoint” reads “Username” and instead of the machine name displays the username.

    Replacing machine name with username

    Replacing Computer/Endpoint with user name

    The line in the XSL file that defines the title of the entry.

    The “host” line in the raw data file. It contains the actual computer/endpoint name.

    This line in the XSL file gets the computer/endpoint name from the “host” line in the raw data file and displays it below the “Computer/Endpoint” entry in the report.

    To replace the “Computer/Endpoint” entry with “Username” and display the username:

    In the XSL specification, replace “Computer/Endpoint” with “Frog user”.

    Also in the XSL specification, replace the variable @host with @user.

    Report username customization

    Report username customization

    Save and close the file.

    Result:

    Report with customized username

    Report with customized username

    Change report message formatting

    In this example, you’ll change the formatting of a specific type of report message.

    As you can see in the image below, messages in the default report with the Success level are printed in green font. Let’s change this to a bold blue font.

    Default successful test validation report message

    Default Success message in green

    Open the CSS specification file.

    Find the color definition for Success messages and copy it.

    Paste it in the customization section at the end of the CSS file and modify it as shown in the image.

    Save and close the file.

    Changing font-color of test validation message

    Default font color definition for Success messages

    New definition in the customization section. Overrides the default definition.

    Note icon

    Note

    Don’t change the default definition (CSS lines #197 to #199). That way, you’ll be able to revert to the default easily.

    Result:

    Changed report with newly formatted test validation message

    Customized Success message

    Remove information from report

    In this example, you’ll remove information from the report. This is useful when something’s not relevant and you want to free up space in the report.

    In our example, we want to remove the Time column for report messages.

    Non-necessary standard report information

    Open the XSL specification file.

    Find all instances of Time in the file.

    CSS default specification for table row time information

    These are the lines that define the Time column in the XSL file.

    Deactivate all of them by commenting them out as shown below.

    Commenting CSS code

    This code gets the time values for each action line and displays them in the correct place.
    Deactivate it by commenting it out as below.

    Commenting CSS code

    Result:

    Custom report with missing time information

    Custom report without Time column