Modern QA demands more than just writing test cases — it requires building scalable, maintainable, and modular automation frameworks. If you're using Selenium with Java, integrating it with Cucumber brings structure and clarity to your test design. But how do you build a modular framework that can scale across projects and teams? Selenium with Java Cucumber This guide walks through how to design a robust Selenium + Cucumber automation framework using Java, following best practices in architecture, reusability, and CI/CD integration. Why Modular Design? A modular automation framework: A modular automation framework: Promotes code reuse and separation of concernsMakes test maintenance easier when UI changes occurAllows for parallel and CI-driven test executionEncourages cleaner collaboration among QA, dev, and business teams Promotes code reuse and separation of concerns code reuse separation of concerns Makes test maintenance easier when UI changes occur Allows for parallel and CI-driven test execution Encourages cleaner collaboration among QA, dev, and business teams Recommended Folder Structure Here's a logical structure to keep the codebase clean and scalable: Here's a logical structure to keep the codebase clean and scalable: lua
CopyEdit
src/test/java
├── base            --> Base classes (WebDriver setup, Hooks)
├── pages           --> Page Object classes
├── stepdefinitions--> Step definitions for Gherkin steps
├── runners         --> Test runners (Cucumber options)
├── utils           --> Utilities like config reader, wait, logs
├── features        --> Gherkin (.feature) files lua
CopyEdit
src/test/java
├── base            --> Base classes (WebDriver setup, Hooks)
├── pages           --> Page Object classes
├── stepdefinitions--> Step definitions for Gherkin steps
├── runners         --> Test runners (Cucumber options)
├── utils           --> Utilities like config reader, wait, logs
├── features        --> Gherkin (.feature) files Tech Stack ComponentToolUI AutomationSelenium WebDriverBDDCucumber + GherkinLanguageJavaBuild ToolMaven GradleTest ReportingAllure ExtentReportsCI/CDJenkins GitHub Actions Setting Up WebDriver & Hooks Base Class: Centralized WebDriver setup Base Class java
CopyEdit
public class BaseTest {
    public static WebDriver driver;

    public void initializeDriver() {
        driver = new ChromeDriver();
        driver.manage().timeouts().implicitlyWait(10, TimeUnit.SECONDS);
        driver.manage().window().maximize();
    }

    public void tearDown() {
        driver.quit();
    }
} java
CopyEdit
public class BaseTest {
    public static WebDriver driver;

    public void initializeDriver() {
        driver = new ChromeDriver();
        driver.manage().timeouts().implicitlyWait(10, TimeUnit.SECONDS);
        driver.manage().window().maximize();
    }

    public void tearDown() {
        driver.quit();
    }
} Hooks Class: To run before and after each scenario Hooks Class java
CopyEdit
public class Hooks {
    BaseTest base = new BaseTest();

    @Before
    public void setup() {
        base.initializeDriver();
    }

    @After
    public void cleanUp() {
        base.tearDown();
    }
} java
CopyEdit
public class Hooks {
    BaseTest base = new BaseTest();

    @Before
    public void setup() {
        base.initializeDriver();
    }

    @After
    public void cleanUp() {
        base.tearDown();
    }
} Page Object Model (POM) Helps encapsulate element locators and actions: java
CopyEdit
public class LoginPage {
    WebDriver driver;

    @FindBy(id = "username") WebElement username;
    @FindBy(id = "password") WebElement password;
    @FindBy(id = "login") WebElement loginBtn;

    public LoginPage(WebDriver driver) {
        this.driver = driver;
        PageFactory.initElements(driver, this);
    }

    public void login(String user, String pass) {
        username.sendKeys(user);
        password.sendKeys(pass);
        loginBtn.click();
    }
} java
CopyEdit
public class LoginPage {
    WebDriver driver;

    @FindBy(id = "username") WebElement username;
    @FindBy(id = "password") WebElement password;
    @FindBy(id = "login") WebElement loginBtn;

    public LoginPage(WebDriver driver) {
        this.driver = driver;
        PageFactory.initElements(driver, this);
    }

    public void login(String user, String pass) {
        username.sendKeys(user);
        password.sendKeys(pass);
        loginBtn.click();
    }
} Feature File (BDD Scenario) gherkin
CopyEdit
Feature: Login functionality

  Scenario: Successful login with valid credentials
    Given User is on login page
    When User enters valid credentials
    Then User is navigated to the homepage gherkin
CopyEdit
Feature: Login functionality

  Scenario: Successful login with valid credentials
    Given User is on login page
    When User enters valid credentials
    Then User is navigated to the homepage Step Definitions java
CopyEdit
public class LoginSteps {
    WebDriver driver = BaseTest.driver;
    LoginPage login = new LoginPage(driver);

    @Given("User is on login page")
    public void userIsOnLoginPage() {
        driver.get("https://example.com/login");
    }

    @When("User enters valid credentials")
    public void userEntersValidCredentials() {
        login.login("testuser", "testpass");
    }

    @Then("User is navigated to the homepage")
    public void userIsOnHomePage() {
        Assert.assertTrue(driver.getTitle().contains("Dashboard"));
    }
} java
CopyEdit
public class LoginSteps {
    WebDriver driver = BaseTest.driver;
    LoginPage login = new LoginPage(driver);

    @Given("User is on login page")
    public void userIsOnLoginPage() {
        driver.get("https://example.com/login");
    }

    @When("User enters valid credentials")
    public void userEntersValidCredentials() {
        login.login("testuser", "testpass");
    }

    @Then("User is navigated to the homepage")
    public void userIsOnHomePage() {
        Assert.assertTrue(driver.getTitle().contains("Dashboard"));
    }
} Reporting Integration Add Allure Maven dependencies: xml
CopyEdit
<dependency>
    <groupId>io.qameta.allure</groupId>
    <artifactId>allure-cucumber6-jvm</artifactId>
    <version>2.13.0</version>
</dependency> xml
CopyEdit
<dependency>
    <groupId>io.qameta.allure</groupId>
    <artifactId>allure-cucumber6-jvm</artifactId>
    <version>2.13.0</version>
</dependency> Use annotations like @Step, @Attachment to enhance test traceability in reports. @Step @Attachment CI/CD with Jenkins Create a Jenkins job linked to your Git repository. Add Maven build step: clean test clean test Post-build step: Publish Allure results Configure triggers for nightly or pull request builds. Best Practices Use @BeforeStep and @AfterStep for fine-grained logs or screenshots. @BeforeStep @AfterStep Avoid hardcoded test data; externalize into .properties or Excel files. .properties Implement RetryAnalyzer to auto-retry flaky tests. RetryAnalyzer Run tests in parallel using TestNG or Cucumber plugin for threads. parallel TestNG Cucumber plugin Final Thoughts A modular Selenium + Cucumber framework is not just about cleaner code — it's about test resilience, scalability, and team collaboration. With the right structure and CI integrations, it can become a powerful asset for any automation team. resilience scalability team collaboration If you're starting out, begin small and scale your framework piece by piece. Over time, this structured approach will save you hundreds of hours in test maintenance and onboarding.

This story contains AI-generated text. The author has used AI either for research, to generate outlines, or write the text itself. 

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

How to Build a Modular Selenium + Cucumber Framework in Java

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Go Beyond Functional Testing: How to Use Playwright for Front-End Performance Insights

Go Beyond Functional Testing: How to Use Playwright for Front-End Performance Insights

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps