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.


There is also a German version of this blog post available: Ranorex Report to PDF German
Please keep in mind that we assume no warranty or assurance with respect to accuracy, correctness and completeness of the translation. Special thanks to Andre Fischer.

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:

PDF Console

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.

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.
    http://www.ranorex.com/support/user-guide-20/lesson-4-ranorex-test-suite.html#c3026
    You should now be able to see the referenced DLL in the reference list in the project view pad.
    Added Library
  • 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).
    PDF NET Framework
  • 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.
    Add Code Module
  • As a last step, simply drag & drop the UserCodeModule to your Ranorex test suite, for example to the teardown section.
    Add Module to Test Suite

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.

Report Entry

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.

Style Sheet

Navigation within the Generated PDF

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

Table of Contents Navigate

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

Navigate Back To TOC

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

Navigate Back To TOC

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 6.2 and lower

Note: When using Ranorex version >= 6.0.0, please make sure to use the “ReportToPDF_6.X.cs”-file for the runtime conversion.
Note: When using Ranorex version >= 6.1.0, please ensure to add a reference to “Ranorex.Libs.Util.dll” to your project. The DLL is located within the installation folder of Ranorex.

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.