Convert your Ranorex Report to PDF

This blog post will show how to use the ReportToPDF tool in order to convert Ranorex Report files into PDF. The platform independent file format allows you to share and distribute the generated reports very easily with people not having Ranorex installed.

• Conversion of an Existing Report
• On-The-Fly Conversion during a Test Run
• Custom Stylesheet
• Navigation within the Generated PDF
• Where Can I Get the ReportToPDF Tool?
• Conclusion

Conversion of an Existing Report

The ReportToPDF executable is a command line tool, which allows you to convert existing Ranorex reports to PDF. The report must be passed to the converter in its compressed form, the so-called “rxzlog”. The “rxzlog” is a single archive (“.rxzlog” extension) including the report and all associated files. More information can be found in the Additional Report Settings section of the Ranorex User Guide.

Using the following call, you can execute the ReportToPDF tool from the command line:

ReportToPDF.exe <input file> <output file> /<argument>

The input and output file need to be set, whereas the arguments are optional.

<input file>

Sets the file (*.rxzlog) which is converted.

<output file>

Sets the name of the PDF file.

Allowed arguments:

style: Sets a custom stylesheet

detail:Specifies how much information is shown within the generated PDF:

• none: no module actions are shown
• failed: only actions from failed modules are shown
• all: all actions are shown (default value)

For example:

Note: When executing a ReportToPDF tool from command line the return value ‘0’ signals a successful execution and the return value ‘-1’ signals a failure.

On-The-Fly Conversion during a Test Run

The ReportToPDF tool is, besides his existence as a command line tool, also available as a DLL (Dynamic Link Library). The Ranorex.PDF.dll allows you to convert the Ranorex Report into a PDF file at the end of a test run. For convenient usage a Ranorex CodeModule (referring the DLL) is available allowing to convert the report with a few clicks.

Note: From Ranorex 7.2, you can directly access the ReportToPDF functionality using the Ranorex Automation Helpers. For detailed instructions, please refer to the user guide section “Ranorex Automation Helpers“.

Steps to be done:

• First of all, you need to reference the Ranorex.PDF.dll within our Ranorex project.
  This can be done by opening the “Add Reference”-dialog (References -> Add Reference) and adding the DLL.
  
  You should now be able to see the referenced DLL in the reference list in the project view pad.
  
• As a next step, you need to set the target framework of the Ranorex project to .NET Framework 4.0 or above. Therefore open the “Compiling”-tab within the project properties (Project -> Properties).
  
• After setting the desired .NET Framework you are ready to add the predefined CodeModule “ReportToPDF.cs” to your project. Open the “Add -> Existing Item”-dialog and add the aforementioned UserCodeModule.
  
• As a last step, simply drag & drop the UserCodeModule to your Ranorex test suite, for example to the teardown section.
  

The “ReportToPDF” code module will trigger the conversion of the report at its current state. A message, containing a link to the PDF file, will be logged to the report after the conversion finishes.

Note: The default filename of the generated PDF is the same as the Ranorex report filename but with a different extension (*.pdf).

Custom Stylesheet

Do you want to change the look and feel of your PDF report? No problem, just use a custom stylesheet in order to change various settings.

For example:

• Specify a custom logo
• Specify margins and indent
• Specify fonts and colors
• etc.

Navigation within the Generated PDF

Each entry of the table of contents is a direct link to the specific test case or module.

Once navigated to the test case/module, you can easily jump back to the table of contents using the link in the header (see screenshot below).

Additionally, you can use the bookmark pane of your PDF viewer in order to navigate through the PDF

Where Can I Get the ReportToPDF Tool?

The ReportToPDF tool is available as a standalone executable as well as in the form of a DLL.

Ranorex 7.0 and higher

• Ranorex_PDF_Executable.zip: executable for conversion of existing report files (*.rxzlog)
• style.zip: stylesheet

Ranorex 6.2 and lower

• Ranorex_PDF_Executable.zip: executable for conversion of existing report files (*.rxzlog)
• Ranorex_PDF_Library.zip: DLL and code module
• style.zip: stylesheet

Version 1.0.10 (October 5, 2017)

Main Features:

• fixed minor issues with empty recordings
• fixed “Object reference not set to an instance of an object.” exception, which was thrown if the TOC was disabled within a custom style.xml

Version 1.0.8 (June 28, 2017)

Bug fixes:

• Added support for Ranorex 7.1, conditional test cases

Version 1.0.7 (March 29, 2017)

Main Features:

• Added support for Ranorex 7.0

Minor Features / Bug fixes:

• Fixed minor issue with empty log messages
• Updated ReportToPDF.cs file to ignore “PDF” within the solution name
• Updated style.xml file to match new report style
• Updated assembly version to Ranorex.PDF version 1.0.7

Breaking Changes:

• Reports created from Ranorex version < 7.0 can’t be converted to PDF format

Version 1.0.5 (September 13, 2016)

• Added (basic) support for HTML messages
• Fixed missing images for image comparisons

Version 1.0.4 (June 2, 2016)

• Fixed duplicate message for Report.Screenshot()-actions
• Added support for Ranorex 6.0
• Fixed bug when using Ranorex Remote

Version 1.0.3 (February 02, 2016)

• Fixed missing report status in PDF file name
• Fixed wrong error return in case of failure

Version 1.0.2 (July 31, 2015)

General changes

• ReportToPDF code module is no longer visible within the generated PDF
• ReportToPDF code module is now placed at the very end of the report, independently of its position within the TestSuite
• Errors which occur during the conversion are no longer part of the report. They are logged to the console instead

Bugs

• Fixed missing total duration
• Fixed bug for disabled “Collect screenshots in a subdirectory”-setting

Version 1.0.1 (July 20, 2015)

• Fixed missing message content
• Fixed PDF output path

Conclusion

The ReportToPDF tool allows both, converting an existing Ranorex Report to PDF using the command line as well as an on the fly conversion at the end of a test run.
Both ways can perfectly be integrated into an already existing Continuous Integration (CI) process. The PDF can easily be shared via mail and/or archived for later usage.