Last Updated Aug 16, 2020 — Guy Arieli, CTO Quality


Serenity BDD Framework Overview

Serenity is an open-source reporting library that enables developers to write easily-understandable and better-structured acceptance criteria for test automation projects. In addition to generating meaningful reports for each test, the tool also shows the list of features tested in each test case. With the details of the executed tests and the requirements that were tested, Serenity BDD Framework allows you to better understand how an application works and what it does.

The good thing about Serenity BDD Framework is that it supports multiple automated acceptance testing solutions. You can use the tool along with JUnit to quickly write clean and maintainable acceptable criteria or integrate it with WebDriver to test web applications in Selenium. It also supports RestAssured to test REST API. Serenity allows you to use any Behaviour-driven Development (BDD) tool such as Cucumber. You can also use any test case management tool such as JIRA or choose a directory-based approach.

What is BDD?

BDD stands for Behavior-driven Development. It has actually evolved from Test-driven Development (TDD) that talks about writing the test cases before writing the code. BDD also takes the same approach but focuses on system behavior and user behavior. In a BDD environment, tests are written in shared language so that all stakeholders (technical and non-technical) will be able to understand how an application works. It also facilitates nice collaboration between different teams. The ability to write test cases in a common language such as English gives a big advantage for developers while preparing acceptance testing criteria. You can write test cases depicting real-time scenarios.

History and Main Concepts of BDD

It was Daniel Terhorst-North who pioneered the development of BDD methodology in 2003. Liz Keogh contributed to the concept in 2004 along with Chris Matts and developed the template ‘Given / When / Then’ for capturing user stories and converting them into an executable form. This concept was inspired by the ‘Domain Driven Design’ written by Eric Evans. Another inspiration was taken from the user story template ‘As a / I / So that’ created by Rachel Davies. In 2005, Dave Astels, David Chelimsky, Steven Baker and Aslak Hellesoy founded RSpec Project that supported BDD in Ruby. While improving this project, Aslak came up with a better version of RSpec Story Runner and he named it Cucumber.

In a BDD approach, requirements are converted into user stories and valid user scenarios.

An example of a BDD template is

  • Given
  • When
  • Then

Another example is

  • As a (premium customer)
  • I want (to browse the new arrivals in the fashion accessories segment)
  • So that (I can order the best apparels)

BDD comes with a minimal learning curve owing to the usage of a shared language. It provides seamless collaboration between different teams. Here, you are defining the behavior and not the test. So, the acceptance criteria is defined before developing the code which is beneficial for business owners as they get a clear understanding of how the application behaves instead of thinking about the features.

Cucumber and Serenity are a couple of popular BDD frameworks.

Getting Started with Serenity BDD Framework

These components run Serenity BDD Framework. They are all required.

  1. Java
  2. IntelliJ IDE
  3. Gradle
  4. Serenity BDD Plugin

Step 1: Install Java

To download Java, visit the following link:

Download the Java Development Kit (JDK)

serenity bdd framework java jdk

Java SE 14.0.2 is the latest release for the Java Standard Edition Platform. Accept the license agreement and proceed with the download.

serenity bdd framework accept

After the software downloads, double-click the application and install Java.

java install serenity bdd framework

Choose the destination folder and click next.

java development kit Serenity bdd framework

The setup package installs Java on your machine. Click close to finish the installation.

serenity bdd framework close

To check if you successfully installed Java, open the command prompt, and type the version command.

  • java -version

java version serenity bdd framework

Step 2: Configure Environment Variables

To use Java, you should configure environment variables. Add Java path under system variables and user variable settings. To do so,

  • Click on System -> Advanced System Settings -> Advanced -> Environment Variables

Check if Java path is added under system variables and user variables path.

Check if Java path is added under system variables

Now Java is ready for use.

Step 3: Install IDE

To write and execute tests using Serenity BDD Framework, you need a modern IDE. You can either choose IntelliJ or Eclipse. To install IntelliJ, visit the following website.

intellij idea serenity bdd framework

Click on the Download button to download the tool. IntelliJ is offered in two versions; Ultimate with a 30-day trial and Community version that is free and open-source. Choose the community version for the test purpose.

intellij idea serenity bdd framework

Now, double-click the IntelliJ software to being the installation procedure.

intellij install

Click next and choose the installation location.

intellij idea

The next screen prompts you to customize installation options.

intellij install

You can create a desktop shortcut or update the context menu. The important feature to note is the ‘Update PATH variable’ option. When you select it, it will automatically configure the environment variables. It means you don’t have to manually add the IntelliJ path to the system variables and user variables.

On the next screen, choose the start menu option and click next to proceed with the installation.

intellij idea

After the installation is completed, it will prompt for a restart. You can choose to manually restart it later.

intellij finish

After the system gets restarted, open the IntelliJ IDE. When you open it for the first time, it will prompt you to accept the privacy policy.

intellij privacy policy

In the next screen, choose your preference for data sharing.

intellij data sharing

Now, the IDE opens up.

intellij serenity bdd framework

So, it is ready for use. You can choose the UI version Dracula (in dark mode) or Light (light mode)

intellij custom

Now, the tool is ready. You can choose a new project or open an existing one.

intellij open

Step 4: Install Gradle

In order to execute tests and generate reports, you should add a built tool such as Maven or Gradle. You can download Maven here:

For Gradle, visit this link:

Create a folder called Gradle in C drive and unzip the Gradle package into that folder.

Step 5: Configure Environment Variable

To use Gradle, you should configure environment variables. Follow the steps mentioned in Step 2 to open the Environment Variables setting. Add the following path under system variables.

  • C:Gradlegradle-6.5.1bin

To check if Gradle is successfully configured, open a command prompt window and type the version command.

  • Gradle -version

serenity bdd framework gradle

So, Gradle is working fine.

Step 6: Add Serenity BDD Plugin

To run your tests using Serenity BDD Framework, you should add the Serenity plugin. To do so, open the IntelliJ IDE.

intellij new

Click on New Project. On the left side menu, choose Gradle.

gradle serenity bdd framework

Choose a name and the location of the build folder and click finish.

gradle finish

The tool will download the necessary files and create a new Gradle project.

gradle download

After the build is completed, it will display a message that the build is successful.

gradle success

Adding Serenity BDD Plugin

To apply the Serenity BDD Framework plugin to the project, open the build.gradle file and edit it with the following code.

[javascript] apply plugin: ‘java’ apply plugin: ‘net.serenity-bdd.aggregator’ repositories { mavenLocal() jcenter() } buildscript { project.ext { serenityVersion = ‘2.2.12’ } repositories { mavenLocal() jcenter() } dependencies { classpath(‘net.serenity-bdd:serenity-gradle-plugin:’ + serenityVersion) } } dependencies { testCompile ‘junit:junit:4.12’ testCompile ‘net.serenity-bdd:serenity-core:’ + serenityVersion testCompile ‘net.serenity-bdd:serenity-junit:’ + serenityVersion testCompile ‘org.assertj:assertj-core:3.4+’ testCompile ‘org.slf4j:slf4j-simple:1.7+’ } gradle.startParameter.continueOnFailure = true [/javascript]

serenity bdd framework

Notice that the code mentions serenityVersion. The latest version is 2.2.12. When you run the code, it will install the Serenity plugin 2.2.12.

serenity bdd framework

Along with the Serenity Gradle plugin, it will install all the dependencies. In this example, the Junit testing library is added. You can choose any other test library as well and add it under dependencies.

serenity bdd framework

Now, open the command prompt window and type the following command.

  • Gradle test aggregate

serenity bdd framework

The build is successful. The test reports are stored in the root folder – C:ExperitestSerenitytargetsiteserenity. When you open the index HTML file, you can check the test reports generated by Serenity BDD Framework. As we have added the continueOnFailure, the tests will continue even though some tests fail.

serenity bdd framework

Running Your First Test

Here is a sample test using a demo site This project authenticates a user login task and checks if the user is able to log in and navigate to the welcome page.

Open your project ExperitestSerenity in the IntelliJ IDE.

open intellij

Here is a list of packages and classes created for the project.

This is the main class that checks if the user is on the Home Page, logins to the account as an admin and successfully navigates to the welcome page.

[javascript] package ExperitestTC1.features.authentication; import ExperitestTC1.steps.DecohereUser; import net.serenitybdd.junit.runners.SerenityRunner; import net.thucydides.core.annotations.Managed; import net.thucydides.core.annotations.Steps; import org.junit.Test; import org.junit.runner.RunWith; import org.openqa.selenium.WebDriver; @RunWith(SerenityRunner.class) public class WhenAuthenticating { @Steps private DecohereUser user; @Managed(driver = “chrome”) WebDriver browser; @Test public void shouldBeAbleToLoginAsAdmin() { user.isOnTheHomePage(); user.logsInAsAdmin(); user.shouldBeOnLandingPage(); } } [/javascript]

This class provides the Home page details for the main class.

[javascript] package ExperitestTC1.steps; import ExperitestTC1.ui.DecohereHomePage; import ExperitestTC1.ui.LandingPage; import net.thucydides.core.annotations.Step; import static org.assertj.core.api.Assertions.assertThat; public class DecohereUser { private DecohereHomePage decohereHomePage; private LandingPage landingPage; @Step public void isOnTheHomePage() {; } @Step public void logsInAsAdmin() { decohereHomePage.loginAsAdmin(); } @Step public void shouldBeOnLandingPage() { assertThat(landingPage.noticeMessage()).isEqualTo(“You are now logged in as”); } } [/javascript]

This class provides the username and password to login to the site.

[javascript] package ExperitestTC1.ui; import net.serenitybdd.core.pages.PageObject; import net.thucydides.core.annotations.DefaultUrl; @DefaultUrl(“”) public class DecohereHomePage extends PageObject { public void loginAsAdmin() { $(“#openLogin”).click(); $(“#username”).sendKeys(“”); $(“#password”).sendKeys(“admin”); $(“#login”).click(); } } [/javascript]

This class shows the welcome page message.

[javascript] package ExperitestTC1.ui; import net.serenitybdd.core.pages.PageObject; public class LandingPage extends PageObject { public String noticeMessage() { return $(“.notice”).getText(); } } [/javascript]

When you run the test in IntelliJ IDE, it will open the Decohere home page and signs-in to the account. The Serenity BDD will generate a report with the test details.

serenity bdd framework results


Serenity BDD Framework’s handy reporting library lets you run better structured and easier to understand acceptance tests. With reports getting generated for each action at every step, developers can understand how each feature is working and quickly identify errors. Serenity Step Libraries enable you to annotate methods with @Step annotation so that you can orchestrate calls to different layers such as databases, web services, and page objects. Overall, Serenity BDD Framework is a good choice when it comes to acceptance testing.

Continuous Testing is about breaking down barriers. See how important continuous testing in the cloud remains in 2021 with this webinar video. 

Are you ready to scale your enterprise?


What's New In The World of

July 22, 2024

Summary of the CrowdStrike Incident and Prevention with Solutions

On July 19, 2024, a faulty software configuration update from…

Learn More
July 15, 2024

Selecting the Right Automated Testing Tools: A Primer

Learn to select the right automated testing tool for your tech stack. From test management to cross-browser testing, we cover the key features you need to know.

Learn More
July 8, 2024

The Logic of Testing: How Speed, Security, and Quality Form a Perfect Script

Discover the logic of testing: how continuous testing, app security, and collaboration unlock speed, security and quality for efficient software delivery.

Learn More