Embedding Custom Data in Serenity Reports

Executable specification written in Gherkin are a great way both to document an application's behaviour, and to demonstrate that it works. QA folk can use the generated living documentation to verify both that the feature does what the business expects of it, and that the feature actually works. Because of this, BDD living documentation plays a key role in accelerating software delivery.

But sometimes, our acceptance tests produce data that we need to store, but that doesn't naturally fit into a BDD-style Given/When/Then format. This might include evidence of test execution such as generated reports or log files, or simple some more detailed information about the test results.

For example, suppose you have a feature related to generating an XML report like the following:

Feature: Exporting to XML

  In order to see my todo items in another application
  As a todo list enthusiast
  I want to export my todo items in a standardized format

  Scenario: Export todo items in XML
    Given that Jane has a todo list containing the following items:
      | Buy some milk |
      | Walk the cat  |
      | Feed the goat |
    When she exports the list in XML
    Then the XML report should contain:
      | title         | status |
      | Buy some milk | Active |
      | Walk the cat  | Active |
      | Feed the goat | Active |

Including raw XML, or even XPath expressions, in a Gherkin scenario would be cumbersome and hard to read. But it is still useful to see the contents of the generated XML report somewhere, without having to look at the code or dig through output directories. This is particularly important in situations where compliance or auditability is important.

This feature is quite simple to use. At any point during test execution, you can include data from a file like this:

Path generatedReport = Paths.get(...);

Serenity.recordReportData().withTitle("Exported XML report")
                           .fromFile(generatedReport);

If you have the contents of the report as a String, you can pass the String directly like this:

String testData = "...";
Serenity.recordReportData().withTitle("Exported XML report")
                           .andContent(testData);

When you run this scenario, a button with the label "Exported XML report" will appear next to the step where you called this method:

If you click on this button, you will see your data:

This feature is available in Serenity version 1.9.16 onwards.