Customization Basics

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

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.

Raw results are saved next to the report file with the same name, plus the suffix .data (for example: MyRun.rxlog.data).

You can open this XML data outside of Ranorex Studio in any XML viewer/editor.

CSS and XSL specifications

Ranorex uses CSS and XSL files stored alongside the report and .data file to generate the final HTML report.

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.

 

Further reading: If you plan to change layout/content (not just colors/logo), basic familiarity with HTML, CSS, XSL, and XML helps a lot. Refer to the World Wide Web Consortium (W3C) at www.w3.org for further reading.

HTML report file

The final HTML report is stored in the project output directory under the Reports folder.

Note: You can open the report in any web browser and edit the HTML in any HTML editor.

To customize reports without modifying the standard template, create a custom template from the test suite properties:

1. In the test suite view, right-click the test suite and select Properties..
   
2. Open the Report tab.
   
3. Click Create custom template. Confirm the message showing where the template folder was created.
   

Result

In Projects view, a new template folder appears containing copied report files:

1. CSS, XSL, and image files: These control report style and structure. The default logo is stored in a PNG (and other report icons/images are there too). You can replace these with your own images.
2. Preview files: Open View.rxlog to preview your customizations quickly (even from Windows, without opening Ranorex Studio).

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:

1. In Properties > Report, click Reset to default.
   
2. Click Create custom template again and confirm.

Result

Another template folder appears in the projects view.

You can rename custom report templates.

1. In the projects view, select the template.
2. Press F2 and rename the template folder.

Warning: Renaming a template folder does not automatically update the active template reference. After renaming, reapply the template (next section).

Use Choose custom template… when you need to:

• Add an existing template from a folder
• Switch between multiple templates
• Reapply a template after renaming

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

1. Open Properties > Report.
2. If a custom template is active, click Reset to default.
3. Click Choose custom template…
4. Select the template folder and click OK.
   

To stop using a custom template:

1. Open Properties > Report.

2. Click Reset to default and confirm.
   

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

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 run tests, Ranorex Studio copies everything needed for execution to the output folder (for example binDebug). This includes your custom template files, but external files (like a new logo you dropped in) are not included by default unless you configure them.

Note: Ranorex Studio synchronizes output-folder files for subsequent runs, so the output always reflects the newest template files.

1. Copy of the customized report template folder (FrogConsulting in this example) in the output folder
2. Reports folder in the output folder
3. Report file (.rxlog) and corresponding raw data file (.rxlog.data)
4. CSS and XSL specification files and default logo file RanorexReport.png

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.

1. 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.
2. During the first test run, the custom template folder is copied directly to the project's output folder.
3. The report layout files (CSS, XSL, and custom files) are also copied directly from the template folder to the Reports folder in the project's output folder.

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.

By default, Ranorex includes internal reporting files (report, data, css/xsl, images/videos). For external files to be copied and available at runtime, you must include them in the project and ensure they are copied to output.

1. Copy the external file(s) into your custom template folder.
2. In Projects view, click Refresh so the file appears.
   
3. Right-click the external file and click Include in project.
4. The file is now included in the project, but we’re not finished yet.
   
5. Select the external file and press F4 to open its properties.

6. 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.

   Note: 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 Project view.

1. Never: Default setting for any newly included external files.
2. Always: It means the file will be copied to the output folder for each test run.
3. Preserve newest: Copied only 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.

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 need a specific size, experiment.

• Know the HEX color values you want to match in the report theme

This is a sample logo. The green background has the HEX value #ACDB6B.

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

Replace the logo

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

1. In Projects view, double-click the CSS file in your custom template.

2. Find the customization area near the end of the file.
   

3. Uncomment the customization section (the article indicates deleting a line that comments it out), then update:
   

 

1. Background customization: The background color is set to the same green HEX value as the logo background color. All other settings are unchanged.
2. 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.
3. Report info box alignment: Finally, a top margin of 40px is set for the general information box.

Result

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 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.

1. The line in the XSL file that defines the title of the entry.
2. The “host” line in the raw data file. It contains the actual computer/endpoint name.
3. 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:

1. In the XSL specification, replace Computer/Endpoint with Frog user.
2. Also in the XSL specification, replace the variable @host with @user.
3. Save and close the file.

Result

In the standard report, Success messages are green by default. This example changes them to bold blue by overriding the style in the customization section.

Note: Don’t change the original default CSS definition. Add an override in the customization section so you can revert easily.

1. Default Success message in green
2. Open the CSS specification file.
3. Find the color definition for Success messages and copy it.
4. Paste it in the customization section at the end of the CSS file and modify it as shown in the image.
5. Save and close the file.
   

• Default font color definition for Success messages
• A new definition is in the customization section. Overrides the default definition.

Result

To remove a column (for example, the Time column in message rows):

1. Open the XSL specification file.
2. Find all instances of Time in the file.
   
   1. These are the lines that define the Time column in the XSL file.
   2. This code gets the time values for each action line and displays them in the correct place.
3. Comment out the relevant blocks that define the column and output its values.
   
4. Deactivate it by commenting it out as below.

Result