Selenium-Java-TestNG-Cucumber Automation Framework

A comprehensive, enterprise-grade automation framework for Web UI testing using Selenium WebDriver, Java, TestNG, and Cucumber (BDD).

🏗️ Framework Architecture

This framework follows industry best practices with a modular, maintainable structure:

• Page Object Model (POM) - Separation of page logic from test logic
• Thread-safe WebDriver - ThreadLocal implementation for parallel execution
• BDD with Cucumber - Business-readable test scenarios
• TestNG - Powerful test execution and parallelization
• ExtentReports & Cucumber Reports - Comprehensive reporting
• CI/CD Ready - Jenkins and GitHub Actions integration

📁 Project Structure

Automation Framework/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/automation/
│   │   │       ├── config/          # Configuration management
│   │   │       │   └── ConfigReader.java
│   │   │       ├── core/            # Core framework components
│   │   │       │   └── DriverManager.java
│   │   │       ├── pages/           # Page Object Model classes
│   │   │       │   ├── BasePage.java
│   │   │       │   └── LoginPage.java
│   │   │       └── utils/           # Utility classes
│   │   │           ├── WaitUtil.java
│   │   │           ├── LoggerUtil.java
│   │   │           ├── ScreenshotUtil.java
│   │   │           ├── AssertionUtil.java
│   │   │           └── RetryUtil.java
│   │   └── resources/
│   │       ├── config/              # Configuration files
│   │       │   ├── config.properties
│   │       │   ├── dev.properties
│   │       │   ├── qa.properties
│   │       │   ├── stage.properties
│   │       │   └── prod.properties
│   │       ├── testdata/            # Test data files
│   │       │   └── testdata.json
│   │       └── log4j2.xml          # Logging configuration
│   └── test/
│       ├── java/
│       │   └── com/automation/
│       │       ├── base/            # Base test classes
│       │       │   └── BaseTest.java
│       │       ├── hooks/           # Cucumber hooks
│       │       │   └── CucumberHooks.java
│       │       ├── runners/         # Test runners
│       │       │   └── TestRunner.java
│       │       └── stepdefinitions/ # Step definitions
│       │           └── LoginStepDefinitions.java
│       └── resources/
│           ├── features/            # Cucumber feature files
│           │   └── Login.feature
│           ├── extent.properties    # ExtentReports config
│           └── extent-config.xml
├── testng.xml                       # TestNG suite configuration
├── testng-parallel.xml              # Parallel execution config
├── testng-smoke.xml                 # Smoke test suite
├── pom.xml                          # Maven configuration
├── Jenkinsfile                      # Jenkins CI/CD pipeline
├── .github/workflows/ci.yml         # GitHub Actions workflow
└── README.md                        # This file

🚀 Prerequisites

• Java 17 or higher
• Maven 3.6+
• Chrome/Firefox/Edge browsers installed (for local execution)
• IDE (IntelliJ IDEA, Eclipse, or VS Code)

📦 Installation & Setup

1. Clone the repository

   git clone <repository-url>
   cd "Automation Framework"

2. Install dependencies

   mvn clean install

3. Configure environment

   • Update src/main/resources/config/config.properties with your application URLs
   • Update environment-specific properties files (dev.properties, qa.properties, etc.)

4. Update test data

   • Modify src/main/resources/testdata/testdata.json with your test data

🎯 Running Tests

Maven Commands

Run all tests

mvn clean test

Run with specific browser

mvn clean test -Dbrowser=chrome
mvn clean test -Dbrowser=firefox
mvn clean test -Dbrowser=edge

Run with specific environment

mvn clean test -Denv=qa
mvn clean test -Denv=dev
mvn clean test -Denv=stage
mvn clean test -Denv=prod

Run with Cucumber tags

mvn clean test -Dcucumber.filter.tags=@smoke
mvn clean test -Dcucumber.filter.tags=@regression
mvn clean test -Dcucumber.filter.tags="@smoke or @regression"

Run in headless mode

mvn clean test -Dheadless=true

Run on Selenium Grid (remote)

mvn clean test -Dexecution.mode=remote -Dgrid.url=http://localhost:4444/wd/hub

Combined example

mvn clean test -Dbrowser=chrome -Denv=qa -Dcucumber.filter.tags=@smoke -Dheadless=false

TestNG XML Execution

Run default suite

mvn clean test

Run parallel suite

mvn clean test -Dsurefire.suiteXmlFiles=testng-parallel.xml

Run smoke suite

mvn clean test -Dsurefire.suiteXmlFiles=testng-smoke.xml

IDE Execution

1. IntelliJ IDEA

   • Right-click on testng.xml → Run
   • Or run TestRunner.java directly

2. Eclipse

   • Right-click on testng.xml → Run As → TestNG Suite

🔧 Configuration

Browser Configuration

Edit src/main/resources/config/config.properties:

browser=chrome                    # chrome, firefox, edge
headless=false                    # true for headless mode
execution.mode=local              # local or remote

Environment Configuration

Environment-specific properties are loaded automatically based on the -Denv parameter:

• dev.properties - Development environment
• qa.properties - QA environment
• stage.properties - Staging environment
• prod.properties - Production environment

Selenium Grid Configuration

For remote execution, configure Grid URL:

grid.url=http://localhost:4444/wd/hub

📊 Reporting

ExtentReports

ExtentReports are generated automatically after test execution:

• Location: test-output/ExtentReports/ExtentReport.html
• Includes screenshots, logs, and detailed test information

Cucumber Reports

Cucumber reports are generated in multiple formats:

• HTML: test-output/cucumber-reports/cucumber.html
• JSON: test-output/cucumber-reports/cucumber.json
• XML: test-output/cucumber-reports/cucumber.xml

View Reports

After test execution, open:

# ExtentReports
open test-output/ExtentReports/ExtentReport.html

# Cucumber HTML Report
open test-output/cucumber-reports/cucumber.html

🔄 Parallel Execution

The framework supports parallel execution at multiple levels:

1. TestNG Parallel Execution

   • Configured in testng-parallel.xml
   • Set thread-count and parallel attributes

2. Cucumber Parallel Execution

   • Enabled in TestRunner.java with @DataProvider(parallel = true)
   • Scenarios run in parallel threads

3. Thread-safe WebDriver

   • Uses ThreadLocal for isolated WebDriver instances
   • Safe for parallel execution

🧩 Adding New Pages

To add a new page to the framework:

1. Create Page Class

   package com.automation.pages;
   
   public class NewPage extends BasePage {
       @FindBy(id = "elementId")
       private WebElement element;
       
       public void performAction() {
           click(element);
       }
   }

2. Create Step Definitions

   package com.automation.stepdefinitions;
   
   public class NewPageStepDefinitions {
       private NewPage newPage = new NewPage();
       
       @When("I perform action")
       public void i_perform_action() {
           newPage.performAction();
       }
   }

3. Create Feature File

   Feature: New Feature
     Scenario: Test scenario
       When I perform action

🐳 Docker & Selenium Grid

Start Selenium Grid with Docker

# Start Grid Hub
docker run -d -p 4444:4444 --name selenium-hub selenium/hub:latest

# Start Chrome Node
docker run -d -p 5555:5555 --link selenium-hub:hub selenium/node-chrome:latest

# Start Firefox Node
docker run -d -p 5556:5555 --link selenium-hub:hub selenium/node-firefox:latest

Run tests against Grid

mvn clean test -Dexecution.mode=remote -Dgrid.url=http://localhost:4444/wd/hub

🔌 CI/CD Integration

Jenkins

1. Create Pipeline Job

   • New Item → Pipeline
   • Point to Jenkinsfile in repository

2. Configure Parameters

   • Browser selection
   • Environment selection
   • Tag selection
   • Execution mode

3. Run Pipeline

   • Build with parameters
   • View reports in Jenkins

GitHub Actions

The framework includes a GitHub Actions workflow (.github/workflows/ci.yml):

• Automatically runs on push/PR
• Supports manual workflow dispatch
• Matrix strategy for multiple browsers
• Artifact upload for reports

🛠️ Framework Features

✅ Implemented Features

• ✅ Page Object Model (POM) pattern
• ✅ Thread-safe WebDriver with ThreadLocal
• ✅ Multiple browser support (Chrome, Firefox, Edge)
• ✅ Headless execution support
• ✅ Selenium Grid support
• ✅ Environment-specific configuration
• ✅ Parallel execution (TestNG & Cucumber)
• ✅ ExtentReports integration
• ✅ Cucumber reporting
• ✅ Screenshot on failure
• ✅ Logging with Log4j2
• ✅ Retry mechanism for flaky tests
• ✅ Explicit waits and synchronization
• ✅ CI/CD integration (Jenkins & GitHub Actions)
• ✅ Tag-based test execution

🔧 Utilities

• WaitUtil - Explicit waits and synchronization
• ScreenshotUtil - Screenshot capture on failure
• AssertionUtil - Custom assertions with logging
• RetryUtil - Retry mechanism for flaky operations
• LoggerUtil - Centralized logging

📝 Best Practices

1. Page Objects

   • Extend BasePage for all page classes
   • Use PageFactory for element initialization
   • Keep page logic separate from test logic

2. Step Definitions

   • One step definition class per feature
   • Reuse page object methods
   • Keep steps simple and readable

3. Feature Files

   • Use descriptive scenario names
   • Tag scenarios appropriately
   • Follow BDD best practices

4. Configuration

   • Use environment-specific properties
   • Never hardcode URLs or credentials
   • Keep test data in separate files

5. Reporting

   • Screenshots are captured automatically on failure
   • Log important steps for debugging
   • Use meaningful assertion messages

🐛 Troubleshooting

Common Issues

1. WebDriver not found

   • WebDriverManager automatically downloads drivers
   • Ensure internet connection for first run

2. Tests fail with timeout

   • Increase wait times in config.properties
   • Check application response time

3. Parallel execution issues

   • Ensure ThreadLocal is used (already implemented)
   • Check thread-count in TestNG XML

4. Reports not generated

   • Run mvn verify after tests
   • Check test-output directory permissions

📚 Dependencies

Key dependencies (see pom.xml for complete list):

• Selenium WebDriver 4.15.0
• TestNG 7.8.0
• Cucumber 7.14.0
• ExtentReports 5.1.1
• Log4j2 2.21.1
• WebDriverManager 5.6.2

🤝 Contributing

1. Follow the existing code structure
2. Add appropriate logging
3. Update documentation
4. Ensure all tests pass

📄 License

This framework is provided as-is for automation testing purposes.

👥 Support

For issues or questions:

• Check the troubleshooting section
• Review logs in logs/automation.log
• Check test output in test-output/

---

Happy Testing! 🚀