Over a million developers have joined DZone.

Serenity BDD Tip: Fine-Tuning Screenshots in Your Living Documentation

John Ferguson Smart describes how taking screenshots in Serenity BDD can slow down WebDriver and explains how to configure your screenshots to avoid this.

· DevOps Zone

The DevOps zone is brought to you in partnership with Sonatype Nexus. The Nexus suite helps scale your DevOps delivery with continuous component intelligence integrated into development tools, including Eclipse, IntelliJ, Jenkins, Bamboo, SonarQube and more. Schedule a demo today

One of the distinguishing features of Serenity BDD is its powerful reporting capabilities. If you organize and structure your tests well, Serenity can help you turn your tests into a sort of light-weight functional documentation, describing both what your application does in high-level terms and how users use the application to achieve specific goals.

As an example, consider the following simple Serenity Screenplay test:

public class WhenPlanningATrip {

    WebDriver webDriver;

    Actor tracy;

    public void setTheStage() {
        tracy = Actor.named("Tracy");

    public void booking_a_simple_trip() {


        // WHEN
                ViewTheAvailableTickets.from("London Paddington").to("Oxford")

        // THEN
                seeThat("the departure station", TheOutboundJourneySummary.origin(), is("London Paddington")),
                seeThat("the destination station", TheOutboundJourneySummary.destination(), is("Oxford"))

This test will produce a test report like the following:

Image title

This kind of detailed report is a great example of living documentation. Testers can use the screenshots to verify that the scenario plays out as they would expect, and product owners get a step-by-step rundown of how a user would interact with the system, including both what they are trying to do (“Tracy chooses to book a ticket,” “Tracy views the available tickets from London to Paddington”) and how they go about it (clicking on buttons, entering field values, and so on).

However, the blow-by-blow detail of the screenshots does come at a cost. Each screenshot request causes WebDriver to pause while it takes the screenshot, and when there are a lot of screenshots, this time can add up and slow down the build pipeline quite significantly. And web-based acceptance tests are naturally slow as it is, so we don’t need them being slowed down further at the wrong time.

Fortunately, screenshots in Serenity BDD are highly configurable. In Serenity 1.1.38, you can configure screenshots according to the type of activity you are doing. For example, you can distinguish how you take screenshots for high-level business tasks (represented by the Task interface in Screenplay, direct interactions with the UI (represented by the Interaction interface), and Questions (assertions) that you ask about the state of the system. For example, the following configuration (placed in the serenity.properties file) would let you record a single screenshot for each task and question, and only record screenshots for interactions if an error occurs:


This sort of fine-tuning can lighten up the reports considerably without compromising the “living documentation” aspect too much, as illustrated here:

Image title

The following figures are by no means scientific, but will give a rough idea of the sort of numbers we are talking about:

Screenshot configurationScreenshots takenIndividual test duration
All screenshots enabled1117 seconds
Screenshots on tasks and questions only412 seconds
Screenshots disabled011 seconds

Many teams using Serenity BDD on larger projects use this approach to configure their builds according to their purpose. For example, standard builds will either limit the screenshots to tasks and questions, or set the screenshot capture to FOR_FAILURE across the board, while a separate “living documentation” build (often run nightly) produces the full set of screenshots and acts as a reference description of the current feature set for product owners, BAs, and testers.

To learn more about Serenity and Serenity Screenplay, be sure to check out the video tutorials that you can find here.

The DevOps zone is brought to you in partnership with Sonatype Nexus. Use the Nexus Suite to automate your software supply chain and ensure you're using the highest quality open source components at every step of the development lifecycle. Get Nexus today


Published at DZone with permission of John Ferguson Smart, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}