Playwright Java BDD Framework Tutorial

As software complexity grows, teams should react and prevent costly failures. With the Behavior-Driven Development (BDD) framework, product owners, programmers, and testers can cooperate using basic text language – simple Gherkin steps to link scenarios to automated tests and make sure they build the right features and functionalities, which meet the needs of the end users.

Based on a recent report, 76% of managers and employees noted that the lack of effective collaboration and clear communication largely contributes to workplace failure. This means that BDD is crucial for various organizations in terms of its capability to guarantee that every member of the team is on the same page and has a clear understanding of the desired software behavior. Let’s find out how the BDD framework can transform the way teams build and test today’s modern software products 😃

What is BDD Framework?

Behavior-driven development (BDD) is a software development methodology, which has a focus on collaborative work between techies and non-techies – developers, testers, and stakeholders throughout the project’s lifecycle. With simple and natural language, teams design apps around a behavior a user expects to utilize. They write descriptions in  Given When Then  format using the user stories before any code is written to be the basis for automated test scenarios.

This BDD approach assists developers and business stakeholders in establishing a clear and common product understanding. The idea is in structuring business requirements and turning them into acceptance tests. Using tests written in plain English, all stakeholders understand and agree on the software’s expected behavior, and make sure that they develop the right software product. In BDD, teams use Gherkin language to write the script in simple words like  Given,  When , and Then . With those words, they describe the behavior of the software.

For example, Gherkin BDD framework scenario:

Feature: Product Search

  Scenario: Display search results when a user searches for a product
    Given a user is on the website
    When they perform a product search
    Then they should see search results

This test script is then turned into automated tests that check if the software behaves as expected and how it is described.

Key principles of BDD Test Framework

• Collaboration. The scenarios are written in a way that all team members – developers, testers, and key stakeholders are in the know how the system should behave regardless of their technical expertise.
• Focus on Behavior. The focus is on the users who are interacting with the product instead of how the software should be built technically.
• Common Language. Simple shared language is used across the business and technical teams so that anyone can understand business requirements and technical implementation.
• Living Documentation. BDD scenarios function as a living documentation. Since these scenarios are automated tests, they provide an up-to-date record of how the system behaves.
• Test Automation. Automating the scenarios allows teams to validate the application behavior once code changes are made. This helps catch regressions early and ensures the system behaves as expected over time.

BDD Framework Life Cycle

BDD life cycle typically includes a series of steps, which make certain that stakeholder communication and the direction of business goals or objectives are unified. Below you can find the key stages:

1. Discover. At this stage, teams collaborate with stakeholders to gain a comprehensive understanding of the project’s scope, objectives, and requirements and establish a roadmap for the project’s execution.
2. Write Scenarios in Gherkin. Teams write scenarios in Given-When-Then format to describe the product’s behavior from the users’ perspectives. These scenarios make it easier for the development teams to understand the requirements and for the QA teams to test them properly.
3. Automate Scenarios. Once scenarios are written, teams convert these plain language scenarios into automated tests using BDD test automation frameworks and tools. These tools parse the Gherkin syntax and map it to test code that interacts with the application.
4. Test. These automated tests are executed frequently to make sure that the system behavior matches the desired behavior after new code is added or existing code is modified.
5. Refactor. Teams improve existing code while maintaining behavior without changing the product’s functionality.
6. Refine and Iterate. Teams update and refine the scenarios to reflect new requirements or changes in the system’s behavior. This creates a feedback loop where the behavior is constantly validated and documented.

Why Use Playwright Java bdd automation framework?

Behavior Driven Development (BDD) with Playwright Java allows you to write tests in a more natural language, which simplifies the process of s understanding and maintaining code quality. Playwright is known as a powerful automation library which enables reliable end-to-end testing across key browser platforms (Chrome/Edge, Firefox, Safari).

Aiming to create robust, understandable, and maintainable automated tests which align with the intended functionality of your application, you can combine BDD principles with Playwright’s automation capabilities in a Java environment.

This approach will work for teams that include non-developers, such as product managers or QA engineers, who need to understand the test cases.

Playwright Cucumber Java Framework: Steps to Follow

So, let’s get started to automate! The typical technology stack for modern Java BDD projects is Java + Playwright + Cucumber together; it is a popular and well-supported choice. Here’s what each part does ⬇️

• Cucumber – handles BDD-style .feature files with Gherkin syntax Given When Then
• Playwright for Java – performs the actual browser automation (clicks, navigation, input, etc.)

Java test automation framework stack includes:

• Maven – the build automation and dependency management tool for Java, is a project heartbeat.
• JUnit (usually JUnit5) – test runner; executes the Cucumber tests.

How to set up our BDD Framework?

Initially, ensure that the Java programming language development environment is installed. It is JDK 17 or higher, and Maven 3.9.3+, of course.

java -version
mvn -v

Node.js (Playwright dependency)

node -v
npm -v

If something is not installed, follow the official links to get started: Java, Playwright, Maven

So, my IDE is VS Code, and I have to install the official Microsoft Extension for Java:

By clicking the button Install you download the set of plugins, allowing you to code in Java with the Visual Studio Code editor freely now.

#1 Step: Create & configure your BDD framework project

There are two options to create a Maven project in VSCode: using the IDE UI by choosing Maven in the New Project wizard or, as in my case, through the CMD command:

mvn archetype:generate -DgroupId=com.example.demo \
-DartifactId=Demo-Java-BDD-framework \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=false

Little explanation for parameters of this command:

• -DgroupId: package name base (like com.yourcompany)
• -DartifactId: Folder/project name
• -DarchetypeArtifactId: Type of project scaffold (quickstart)
• -DinteractiveMode=false: Prevents Maven from asking prompts

Once the project is created, in the editor, you will see an auto-generated basic pom.xml and project structure:

Pay attention to the Maven build notification in the bottom right-hand corner. You should agree every time after savings in the BDD framework project, anyway, to do it manually with the command:

mvn clean install

#2 Step: Configure Dependencies

The following action is adding dependencies via Maven in the pom.xml file:

• playwright
• cucumber-java
• cucumber-junit

Check the Playwright dependencies of the new version you can on the Playwright Java page

To avoid errors, you can alternatively install Playwright Java at one time:

mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install"

Similarly, you can find the required dependencies on the official Cucumber documentation page at the following link and JUnit(usually JUnit5) Dependency Page information. These configurations enable automation of step definitions and browser interactions.

Eventually, this is a minimal BDD framework example of dependencies for Playwright, Cucumber and JUnit:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.saucedemo</groupId>
    <artifactId>playwright-tests</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>23</maven.compiler.source>
        <maven.compiler.target>23</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.microsoft.playwright</groupId>
            <artifactId>playwright</artifactId>
            <version>1.52.0</version>
        </dependency>

          <dependency>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-java</artifactId>
            <version>7.23.0</version>
        </dependency>

       <dependency>
            <groupId>io.cucumber</groupId>
            <artifactId>cucumber-junit</artifactId>
            <version>7.23.0</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

  </project>

After saving pom.xml, compile the Maven build again

#3 Step: Create a Cucumber Runner

Create a TestRunner.java class file. The TestRunner.java class is like the engine that wires everything together. It tells Cucumber how to find and run .feature files.

Example TestRunner Java:

package runner;

import org.junit.runner.RunWith;
import io.cucumber.junit.Cucumber;
import io.cucumber.junit.CucumberOptions;

@RunWith(Cucumber.class)
@CucumberOptions(
    features = "src/test/resources/features",
    glue = "steps",
    plugin = {"pretty", "html:target/cucumber-report.html"},
    monochrome = true
)
public class TestRunner {
}

The BDD framework structure of the project, as you can see in this picture, keeps logic separate and testable:

src
└── test
    ├── java
    │   ├── runners
    │   │   └── TestRunner.java
    │   └── steps
    │       └── LoginSteps.java
    └── resources
        └── features
            └── Login.feature

#4 Step: Write feature files with scenarios in Gherkin

Create  .feature files, look at the top of the code path where it is placed 👀

Feature: Login to Sauce Demo

  Scenario: Successful login with valid credentials
    Given I open the login page
    When I enter username "standard_user" and password "secret_sauce"
    And I click the login button
    Then I should see the products page

#5:Step Map steps in Java using Cucumber step definitions

package steps;

import com.microsoft.playwright.*;
import io.cucumber.java.After;
import io.cucumber.java.Before;
import io.cucumber.java.en.*;

import static org.junit.Assert.assertTrue;

public class LoginSteps {
    Playwright playwright; // Variable playwright type of Playwright object
    Browser browser; // Represents a specific browser instance (e.g.Chromium)
    Page page; // Represents a single tab or page within the browser.

    @Before //Hook - runs before each scenario
    public void setUp() {
        playwright = Playwright.create(); //Initializes Playwright engine
        browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(false)); //Launches a visible Chromium Browser
        page = browser.newPage(); //opens a new Browser Tab
    }

    @Given("I open the login page")
    public void openLoginPage() {
        page.navigate("https://www.saucedemo.com/"); //Navigates to Log In page
    }

    @When("I enter username {string} and password {string}")
    public void enterCredentials(String username, String password) {
        page.fill("#user-name", username); //Fills in username
        page.fill("#password", password); //Fills password
    }

    @When("I click the login button")
    public void clickLogin() {
        page.click("#login-button"); //Clicks login button
    }

    @Then("I should see the products page")
    public void verifyProductsPage() {
        assertTrue(page.isVisible(".inventory_list")); //Checks of inventory list is visible
    }

    @After
    public void tearDown() {
        browser.close(); //closes browser page
        playwright.close(); // shuts down playwright engine
    }
}

#6:Step Run tests via JUnit5 runner

mvn clean test

🎉 Output

Opens browser using Playwright, navigates to login page, completes the login, verifies the dashboard is displayed and generates a basic Cucumber HTML report. Thus,

– Where can we find this BDD framework’ Cucumber HTML report?

Enter into the folder target, scroll down and launch Cucumber HTML report. It is automatically generated when Cucumber tests run with the proper configuration, namely:

@CucumberOptions(
    plugin = {"pretty", "html:target/cucumber-report.html"}
)

The Cucumber HTML Report is a simple and quite user-friendly visual representation test results of your BDD (Behavior-Driven Development) framework. It shows: Feature and Scenario breakdown, their steps in detail and result, Pass/Fail status, Error messages and stack traces, execution time. In total, it is not very informative, but it is not too bad either.

What is Playwright Test Report?

Generally, a Playwright test reports works as an extensive summary compiled after running a set of automated tests using the Playwright testing framework and indicates which scenarios passed, failed, or skipped.

With detailed reports, developers and test engineers can quickly identify the root cause of test failures and debug issues in the application code or the test automation itself. They can analyze reports to highlight areas of the application’s behavior that are not yet adequately covered by automated tests and create more scenarios.

The Testomatio Playwright Test Report Key Components

If a simple, basic Playwright or Cucumber HTML report is not enough, our solution is the perfect fit. The test management system testomat.io offers powerful Reporting and Analytics across different testing types.

In this test reporting, you can find the following information:

• Manual testing, as well as automation testing, in one place.
• Customizable test plans, selective test case execution. Easy to share it with stakeholders.
• Information on test status –  which tests have been passed, failed, or skipped.
• Descriptions of any errors, mentioning the type of error and the location.
• How long the test runs in order to identify slow tests and areas which cause performance delays.
• Information about test coverage.
• Screenshots or video recordings of the test execution to better understand the test results.
• Full test run history and clear progress tracking.
• Detailed logs that can help developers debug issues and offer visibility into browser actions, network requests, and responses.
• Moreover, actionable analytics with a wide range of metrics and insights to support decision-making.

Start by adding the Java JUnit XML plugin to the pom.xml file:

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.2.5</version> <!-- or the latest -->
      </plugin>
    </plugins>
  </build>

Sign up or log in to the TMS, then create your test project by following the system’s guidance, and then import BDD tests. Only follow the smart tips the test management UI offers.

This is the result of syncronization of manual and auto tests in the common repository.

In addition, testomat.io offers a unique feature that allows automatic converting of classical manual test cases into BDD (Behavior-Driven Development) format and importing detected steps into the Reusable Steps Database. Especially, this capability is useful for teams transitioning from traditional manual QA workflows to modern, executable BDD-style automation.

It seems this report offers a more polished presentation than the standard Cucumber report, doesn’t it?

Advantages of BDD Playwright Java framework

• Step Definition Mapping. Teams can use Given/When/Then annotations with accurate regular expressions to link Gherkin steps to Java methods.
• Playwright API Interaction. Teams can apply Playwright’s Page, Locator, and browser management APIs within step definitions in order to automate browser actions and assertions.
• Test Reporting. Teams can correctly specify the paths to Feature Files (features) and Step Definition packages (glue), which contain your automation code to set up how test results are reported and provide meaningful feedback once tests are executed.
• Parameter Passing in Steps. Teams can use capture groups in regular expressions within step annotations to pass data from Gherkin scenarios to Java methods,  because it allows them to write more reusable step definitions that can handle various data inputs from the Feature Files, and cut down code duplication.
• Assertions. With assertion methods within step definitions, teams can verify that the actual application’s behavior matches the expected outcomes defined in the Gherkin scenarios, which makes the tests reliable and verifies the software works as designed
• Selector Strategies.  With Playwright’s selector types (CSS, XPath, text-based) and reliable web elements identification, teams can automate code to accurately target and interact with specific UI elements, even after changes in the application’s structure or styling.
• Handling Asynchronous Operations.  Understanding that Playwright’s API is asynchronous and ensuring proper handling, teams can prevent their automation code from prematurely proceeding before UI elements are fully loaded or actions are completed, which contributes to more reliable and less flaky tests that accurately reflect user interactions.
• Integration with CI\CD. Teams can configure the build process to execute tests and generate reports in a continuous integration environment.

Interesting to read:

• Cucumber BDD framework for API testing with Playwright example
• Behavior-Driven Development (BDD): Meaning, Benefits & Best Practices
• Integration between BDD in Jira and Test Management System

Disadvantages of BDD test framework with Playwright Java

• Steeper Learning Curve & Complex Project Setup. If teams are new to both BDD principles and Playwright Java, it requires significant effort from them to set up the necessary dependencies.
• Complex Project Setup. Setting up the necessary dependencies (Cucumber, Playwright, Test Runner, reporting libraries) in a Java project can be more involved than setting up simpler testing frameworks.
• Too UI-centric Scenarios. Teams might fall into the trap of writing excessively detailed Gherkin scenarios that become difficult to maintain and understand. Scenarios should focus on business value, not low-level UI interactions.
• Not a Replacement for All Testing. While BDD with Playwright Java focuses on end-to-end or integration software testing from a user’s perspective, it doesn’t serve the purpose of unit tests or API tests.
• Slower Performance. Running end-to-end tests driven by Cucumber and Playwright can be slower than unit or integration tests. While Playwright is generally fast, the overhead of interpreting Gherkin and orchestrating browser actions can add to execution time, especially for large test suites.
• Maintenance Challenges. Playwright tests are susceptible to changes in the application’s user interface, meaning any minor UI modifications can break a significant number of scenarios and need frequent updates to reflect changes in UI elements, workflows, or data.
• Synchronization Issues. Web applications can be asynchronous, and handling synchronization (waiting for elements to load, animations to complete) in Playwright Step Definitions requires careful implementation to avoid flaky tests.
• Cooperation Problems. If business stakeholders are not involved in writing and reviewing feature files, the scenarios might not accurately reflect business needs.

Bottom Line: Ready To Develop The Right Product The Right Way with BDD Playwright Java?

When it comes to incorporating the Behavior-Driven Development (BDD) testing framework, organizations need to remember that it is not just a methodology; it’s a mindset. Furthermore, its adoption becomes a crucial strategy for organizations which require revolutionizing how they approach the software development process.

With BDD practice in place, you can improve communication, catch bugs early, enhance documentation, and increase test coverage. Contact our specialists if you aim to navigate software development complexities and need a working approach like BDD to develop features, which are well-understood by both technical and business stakeholders. Only by utilizing the correct BDD tools and frameworks can you get BDD’s highest potential to achieve success in your projects.