Selenium + Java + Cucumber + TestNG Framework

A robust, enterprise-level test automation framework using Selenium WebDriver, Cucumber BDD, TestNG, and Gradle.

🏗️ Framework Architecture

selenium-cucumber-framework/
├── src/
│   ├── main/
│   │   ├── java/com/automation/
│   │   │   ├── pages/           # Page Object Model classes
│   │   │   │   ├── BasePage.java (100+ reusable methods)
│   │   │   │   └── LoginPage.java
│   │   │   └── utils/           # Utility classes
│   │   │       ├── ConfigReader.java
│   │   │       ├── DriverManager.java
│   │   │       ├── ScreenshotUtil.java
│   │   │       └── RetryAnalyzer.java
│   │   └── resources/
│   │       └── config.properties
│   └── test/
│       ├── java/com/automation/
│       │   ├── runners/         # TestNG Cucumber Runners
│       │   │   ├── TestRunner.java
│       │   │   └── SmokeTestRunner.java
│       │   ├── stepdefinitions/ # Cucumber Step Definitions
│       │   │   └── LoginSteps.java
│       │   └── hooks/           # Cucumber Hooks
│       │       └── Hooks.java
│       └── resources/
│           ├── features/        # Cucumber Feature files
│           │   └── Login.feature
│           ├── testdata/        # Test data files
│           └── testng.xml       # TestNG suite configuration
├── build.gradle
├── settings.gradle
├── gradle.properties
└── README.md

✨ Key Features

🎯 Core Features

• ✅ Page Object Model (POM) design pattern
• ✅ Cucumber BDD for behavior-driven testing
• ✅ TestNG for test execution and management
• ✅ Gradle build automation
• ✅ Enterprise-level BasePage with 100+ reusable methods
• ✅ Retry Analyzer for automatic failed test retry
• ✅ Screenshot on Failure capability
• ✅ Allure Reports - Beautiful, interactive HTML reports
• ✅ Multiple Reporting (Cucumber HTML, JSON, XML, Allure)
• ✅ Parallel Execution support
• ✅ Cross-browser testing support
• ✅ WebDriverManager for automatic driver management

🛠️ BasePage Capabilities (100+ Methods)

The framework includes a comprehensive BasePage with advanced methods organized in categories:

Click Methods (7 types)

• Standard click, JavaScript click, Actions click
• Double-click, Right-click, Click and hold

Input/SendKeys Methods (6 types)

• SendKeys with/without clear, JavaScript input
• Slow typing, Field clearing

Dropdown Handling (7 types)

• Select by text/value/index
• Get all options, Multi-select support
• Deselect operations

Advanced Wait Strategies (10 types)

• Explicit waits, Fluent waits
• Custom waits, AJAX/jQuery waits
• Page load waits, Element visibility waits

Mouse Actions (5 types)

• Hover, Hover and click
• Drag & Drop, Drag by offset

Scroll Operations (6 types)

• Scroll to element (smooth/regular)
• Scroll to top/bottom
• Scroll by pixels

Alert Handling (5 methods)

• Accept, Dismiss, Get text
• Send text, Check presence

Frame/Window Management (9 methods)

• Switch frames (by index/name/element)
• Switch windows, Close windows
• Navigate between windows

JavaScript Executor (5 methods)

• Execute scripts, Highlight elements
• Set/Remove attributes

Navigation Methods (6 methods)

• Navigate to URL, Refresh, Back, Forward
• Get current URL and title

Screenshot Methods (2 types)

• Full page screenshots
• Element-specific screenshots

List/Table Operations (3 methods)

• Get all elements text
• Click element by text
• Find element by text

Keyboard Actions (7 methods)

• Press Enter/Tab/specific keys
• Keyboard shortcuts
• Copy/Paste operations

📋 Prerequisites

• Java JDK: 17 or higher
• Gradle: 7.x or higher (or use Gradle wrapper)
• IDE: IntelliJ IDEA / Eclipse / VS Code
• Browsers: Chrome (default), Firefox, Edge, or Safari

🚀 Setup Instructions

1. Navigate to Framework Directory

cd /Users/doddakulanagendrababu/Documents/selenium-cucumber-framework

2. Install Dependencies

./gradlew clean build

Or on Windows:

gradlew.bat clean build

3. Configure Test Settings

Edit src/main/resources/config.properties:

# Application URL
app.url=https://doddakula-nagendrababu-ai-testcase.vercel.app/login.html

# Browser Configuration
browser=chrome
headless=false
browser.window.maximize=true

# Timeouts
implicit.wait=10
explicit.wait=20
page.load.timeout=30

# Test Credentials
test.username=testuser@example.com
test.password=Test@123

# Retry Configuration
retry.count=2

# Screenshot Configuration
screenshot.on.failure=true
screenshot.path=test-output/screenshots/

▶️ Running Tests

Run All Regression Tests

./gradlew clean test

Run via TestNG XML

./gradlew clean test -Dsuite=src/test/resources/testng.xml

Run Smoke Tests Only

./gradlew clean test -Dcucumber.filter.tags="@Smoke"

Run with Specific Tags

# Run Login tests
./gradlew clean test -Dcucumber.filter.tags="@Login"

# Run Positive tests
./gradlew clean test -Dcucumber.filter.tags="@Positive"

# Run Negative tests
./gradlew clean test -Dcucumber.filter.tags="@Negative"

# Run multiple tags (AND condition)
./gradlew clean test -Dcucumber.filter.tags="@Smoke and @Login"

# Run multiple tags (OR condition)
./gradlew clean test -Dcucumber.filter.tags="@Smoke or @Regression"

Run in Headless Mode

Update config.properties:

headless=true

Run with Different Browser

Update config.properties:

browser=firefox  # Options: chrome, firefox, edge, safari

Run Specific Runner

# Run TestRunner
./gradlew clean test --tests "com.automation.runners.TestRunner"

# Run SmokeTestRunner
./gradlew clean test --tests "com.automation.runners.SmokeTestRunner"

📊 Test Reports

After test execution, reports are generated in multiple formats:

Allure Report (Recommended) 📊

# Generate and view Allure report
allure serve build/allure-results

Location: build/allure-report/ Features: Interactive, beautiful HTML reports with screenshots, trends, and detailed analytics

📖 See ALLURE_SETUP.md for detailed Allure installation and usage guide

Cucumber HTML Report

target/cucumber-reports/cucumber.html

Cucumber JSON Report

target/cucumber-reports/cucumber.json

Cucumber XML Report (for CI/CD)

target/cucumber-reports/cucumber.xml

TestNG Report

test-output/index.html

Screenshots (on failure)

test-output/screenshots/

View Reports

# View Cucumber report
open target/cucumber-reports/cucumber.html

# View Allure report
allure serve build/allure-results

🧪 Writing New Tests

Step 1: Create Feature File

Create a new .feature file in src/test/resources/features/:

@NewFeature @Regression
Feature: New Feature Description
  As a user
  I want to test new functionality
  So that I can ensure it works correctly

  Background:
    Given User is on the application

  @Smoke @Positive
  Scenario: Valid scenario description
    When User performs an action
    And User performs another action
    Then User should see expected result

  @Negative
  Scenario: Invalid scenario description
    When User performs invalid action
    Then User should see error message

Step 2: Create Page Object

Create a new page class in src/main/java/com/automation/pages/:

package com.automation.pages;

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.WebElement;
import org.openqa.selenium.support.FindBy;

public class NewPage extends BasePage {

    // Locators
    @FindBy(id = "elementId")
    private WebElement element;

    @FindBy(xpath = "//button[@type='submit']")
    private WebElement submitButton;

    // Constructor
    public NewPage(WebDriver driver) {
        super(driver);
    }

    // Action Methods
    public void clickElement() {
        click(element);
    }

    public void enterText(String text) {
        sendKeys(element, text);
    }

    public String getElementText() {
        return getText(element);
    }

    public boolean isElementDisplayed() {
        return isDisplayed(element);
    }
}

Step 3: Create Step Definitions

Create step definitions in src/test/java/com/automation/stepdefinitions/:

package com.automation.stepdefinitions;

import com.automation.pages.NewPage;
import com.automation.utils.DriverManager;
import io.cucumber.java.en.*;
import org.testng.Assert;

public class NewSteps {
    private NewPage newPage;

    @Given("User is on the application")
    public void user_is_on_the_application() {
        DriverManager.getDriver().get("URL");
        newPage = new NewPage(DriverManager.getDriver());
    }

    @When("User performs an action")
    public void user_performs_an_action() {
        newPage.clickElement();
    }

    @Then("User should see expected result")
    public void user_should_see_expected_result() {
        Assert.assertTrue(newPage.isElementDisplayed(), "Element not displayed");
    }
}

🔧 Configuration Options

config.properties Options

Property	Description	Default	Example
app.url	Application URL	-	https://example.com
browser	Browser name	chrome	chrome/firefox/edge/safari
headless	Run in headless mode	false	true/false
browser.window.maximize	Maximize browser window	true	true/false
implicit.wait	Implicit wait (seconds)	10	10
explicit.wait	Explicit wait (seconds)	20	20
page.load.timeout	Page load timeout (seconds)	30	30
retry.count	Retry attempts for failed tests	2	0-5
screenshot.on.failure	Take screenshot on failure	true	true/false
screenshot.path	Screenshot directory path	test-output/screenshots/	custom/path/
test.username	Test username	-	user@example.com
test.password	Test password	-	Pass@123

🎭 Parallel Execution

Enable Parallel Execution

Update src/test/java/com/automation/runners/TestRunner.java:

@DataProvider(parallel = true)
public Object[][] scenarios() {
    return super.scenarios();
}

Update src/test/resources/testng.xml:

<suite name="Test Suite" parallel="methods" thread-count="3">

Thread Count Configuration

• Set thread-count="3" for 3 parallel threads
• Adjust based on your machine's capacity
• Recommended: CPU cores - 1

🐛 Debugging & Troubleshooting

Enable Verbose Logging

Update testng.xml:

<suite name="Test Suite" verbose="10">

Highlight Elements During Execution

In your test code:

basePage.highlightElement(element);

Dry Run (Validate Step Definitions)

Update TestRunner.java:

dryRun = true  // Will not execute, just validate

Common Issues

Issue: WebDriver not found Solution: Run ./gradlew clean build to download dependencies

Issue: Screenshot directory not found Solution: Framework auto-creates it, but ensure write permissions

Issue: Tests not running Solution: Check tags in TestRunner match feature file tags

📝 Framework Best Practices

1. Page Objects

• ✅ One page class per web page
• ✅ Use meaningful element names
• ✅ Keep page objects independent
• ✅ Extend BasePage for all page classes

2. Step Definitions

• ✅ Keep steps simple and readable
• ✅ Delegate to page objects (no direct Selenium code)
• ✅ One step definition file per feature
• ✅ Reuse existing steps where possible

3. Feature Files

• ✅ Use descriptive scenario names
• ✅ Tag appropriately (@Smoke, @Regression, etc.)
• ✅ Keep scenarios independent
• ✅ Use Background for common preconditions
• ✅ Use Scenario Outline for data-driven tests

4. Waits

• ✅ Always use explicit waits (from BasePage)
• ✅ Never use Thread.sleep()
• ✅ Use appropriate wait types for the situation

5. Assertions

• ✅ Use TestNG assertions in step definitions
• ✅ Provide meaningful assertion messages
• ✅ Assert expected outcomes clearly

6. Configuration

• ✅ Keep all configs in config.properties
• ✅ Never hardcode URLs or credentials
• ✅ Use environment-specific properties if needed

7. Reporting

• ✅ Take screenshots on failure (enabled by default)
• ✅ Use meaningful scenario and step names
• ✅ Add tags for better report filtering

📁 Project Structure Explained

src/main/java/com/automation/
├── pages/              # Page Object Model
│   ├── BasePage.java   # Base class with 100+ reusable methods
│   └── LoginPage.java  # Login page object
└── utils/              # Utility classes
    ├── ConfigReader.java      # Reads config.properties
    ├── DriverManager.java     # WebDriver lifecycle management
    ├── ScreenshotUtil.java    # Screenshot capture utility
    └── RetryAnalyzer.java     # TestNG retry analyzer

src/test/java/com/automation/
├── runners/            # TestNG Cucumber runners
│   ├── TestRunner.java      # Main test runner
│   └── SmokeTestRunner.java # Smoke test runner
├── stepdefinitions/    # Cucumber step implementations
│   └── LoginSteps.java
└── hooks/              # Cucumber hooks
    └── Hooks.java      # Before/After scenario hooks

src/test/resources/
├── features/           # Cucumber feature files (BDD)
│   └── Login.feature
├── testdata/           # Test data files (CSV, JSON, Excel)
└── testng.xml          # TestNG suite configuration

🔗 Dependencies

Key dependencies managed by Gradle:

• Selenium WebDriver 4.18.1: Browser automation
• Cucumber 7.15.0: BDD framework
• TestNG 7.9.0: Test execution framework
• Allure 2.25.0: Advanced reporting
• WebDriverManager 5.6.3: Automatic driver management
• Apache POI 5.2.5: Excel operations
• AssertJ 3.25.1: Fluent assertions
• Gson/Jackson: JSON handling
• Log4j 2.22.1: Logging

🚀 CI/CD Integration

Jenkins

pipeline {
    agent any
    stages {
        stage('Test') {
            steps {
                sh './gradlew clean test'
            }
        }
        stage('Allure Report') {
            steps {
                allure includeProperties: false,
                       jdk: '',
                       results: [[path: 'build/allure-results']]
            }
        }
        stage('Cucumber Report') {
            steps {
                cucumber '**/cucumber.json'
                publishHTML([reportDir: 'target/cucumber-reports', reportFiles: 'cucumber.html'])
            }
        }
    }
}

GitHub Actions

name: Selenium Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up JDK 17
        uses: actions/setup-java@v2
        with:
          java-version: '17'
      - name: Run tests
        run: ./gradlew clean test
      - name: Generate Allure Report
        run: allure generate build/allure-results --clean -o build/allure-report
      - name: Upload Allure Report
        uses: actions/upload-artifact@v2
        with:
          name: allure-report
          path: build/allure-report/
      - name: Upload Cucumber reports
        uses: actions/upload-artifact@v2
        with:
          name: cucumber-reports
          path: target/cucumber-reports/

📞 Support & Maintenance

Framework Maintainer

• Location: /Users/doddakulanagendrababu/Documents/selenium-cucumber-framework
• Application Under Test: https://doddakula-nagendrababu-ai-testcase.vercel.app/login.html

Getting Help

• Check this README first
• Review BasePage methods for available actions
• Examine existing tests for examples
• Check Gradle build logs for dependency issues

📈 Future Enhancements

Potential improvements for the framework:

• API testing integration (RestAssured)
• Database validation utilities
• Email/SMS verification helpers
• Docker containerization
• Performance testing integration
• Visual regression testing
• Allure Reports integration ✅ Completed

---

🎓 Quick Start Example

# 1. Navigate to project
cd /Users/doddakulanagendrababu/Documents/selenium-cucumber-framework

# 2. Build project
./gradlew clean build

# 3. Install Allure (if not installed)
brew install allure

# 4. Run tests
./gradlew clean test

# 5. View Allure report (recommended)
allure serve build/allure-results

# Or view Cucumber report
open target/cucumber-reports/cucumber.html

---

Framework Created: October 2025 Test Automation Framework: Selenium + Java + Cucumber + TestNG + Gradle + Allure Ready to Use: Yes ✅

📊 View Allure Setup Guide

Happy Testing! 🚀