SeleniumBDD Automation Framework

🌐 Language / Idioma

🇬🇧 English   |   🇪🇸 Español

Java-based QA automation framework built with Selenium + Cucumber + JUnit 6, designed to demonstrate maintainable UI test architecture, Maven-driven execution, and bilingual documentation suitable for technical review and portfolio presentation.

---

🎯 Why This Project Matters

This repository is designed as a QA Automation portfolio project that demonstrates more than automated UI checks. It highlights how to structure a maintainable Selenium-based framework with clear execution flow, reusable automation design, and documentation that reflects engineering discipline.

It demonstrates practical QA automation concepts such as:

• BDD with Cucumber for readable business scenarios
• Page Object Model (POM) for maintainability and separation of concerns
• Maven-driven execution for predictable local and CI-oriented runs
• Structured reporting through maven-cucumber-reporting
• Bilingual documentation for broader readability and stronger repository presentation
• Framework evolution awareness, including the migration from JUnit 5 to JUnit 6

This project demonstrates QA automation best practices with Java, Selenium, Cucumber, and JUnit, including maintainable architecture, reusable automation design, clear documentation, and framework scalability.

---

🚀 Project Overview

This repository contains an end-to-end UI automation framework implemented with:

• Java 17
• Selenium WebDriver
• Cucumber JVM
• JUnit 6
• Maven
• maven-cucumber-reporting
• Page Object Model (POM)
• Reusable utilities, hooks, and structured project organization

🔗 Repository: https://github.com/CarlosArman/SeleniumBDD

---

✨ What This Framework Demonstrates

Engineering Practices

• ✅ Page Object Model architecture
• ✅ BDD-oriented scenario structure with Cucumber
• ✅ Maven Wrapper-based execution
• ✅ JUnit Platform execution with JUnit 6 dependencies
• ✅ Report generation during Maven verify
• ✅ Separation between hooks, pages, steps, data, and utilities
• ✅ Bilingual documentation for maintainability and portfolio clarity

QA Portfolio Value

• ✅ Maintainable automation design
• ✅ Practical reporting strategy
• ✅ Clear execution approach with Maven lifecycle integration
• ✅ Documented framework evolution from JUnit 5 to JUnit 6
• ✅ Clean project organization and cross-referenced documentation
• ✅ Repository structure ready to grow into CI/CD workflows

---

🏗 Project Structure

SeleniumBDD
├── src/
│   ├── main/
│   └── test/
│       ├── java/
│       │   ├── data/         # Test data readers, builders, and structured input helpers
│       │   ├── hooks/        # Lifecycle hooks, setup/teardown, and evidence handling
│       │   ├── modelos/      # Domain models used by the automation flows
│       │   ├── pages/        # Page Object Model classes and reusable UI interactions
│       │   ├── principal/    # Runner or bootstrap classes for execution
│       │   ├── steps/        # Step definitions that map Gherkin steps to automation logic
│       │   └── utilities/    # Helpers, waits, logging, and support logic
│       └── resources/
│           ├── features/     # Gherkin feature files and business-readable scenarios
│           ├── data/         # External test data files
│           └── junit-platform.properties
├── .mvn/                     # Maven Wrapper support files
├── docs/                     # Additional project documentation
├── runSuite.sh               # Example local execution script
├── openReport.sh             # Example script to open the generated report
├── pom.xml                   # Project dependencies, plugins, and execution configuration
├── CHANGELOG.md              # Project changelog in English
├── CHANGELOG.es.md           # Historial de cambios en Español
├── CONTRIBUTING.md           # Contribution guide in English
├── CONTRIBUTING.es.md        # Guía de contribución en Español
├── README.md                 # Main documentation in English
└── README.es.md              # Main documentation in Spanish

---

⚙ Quick Start

1. Clone the repository

git clone https://github.com/CarlosArman/SeleniumBDD.git
cd SeleniumBDD

2. Validate prerequisites

Make sure you have:

• JDK 17
• JAVA_HOME configured
• Maven Wrapper available from the repository
• A valid browser driver strategy (drivers on PATH, a driver manager approach, or an equivalent local setup)

For environment details, see:

• docs/ENVIRONMENT.md
• docs/ENVIRONMENT.es.md

3. Run tests

./mvnw clean test -Dgroups="regression" -Dbrowser="edge"

4. Generate the report

./mvnw verify

---

▶ Main Commands

The primary README should expose only the most important commands. For the full catalog, see docs/COMMANDS.md and docs/COMMANDS.es.md.

./mvnw clean test -Dgroups="regression" -Dbrowser="edge"
./mvnw verify
./runSuite.sh
./openReport.sh

---

📊 Reporting and Evidence

This framework documents a reporting strategy based on the current Maven configuration:

• Cucumber HTML report generated through maven-cucumber-reporting
• Maven verify phase used as the report generation step
• Report output directory under target/site
• Report project name configured as SeleniumBDD Automation Framework
• Consistent evidence strategy expected through hooks/utilities when implemented

Expected HTML report path:

target/site/cucumber-html-reports/overview-features.html

If the effective generated file differs in your local run, update openReport.sh and the documentation to match the real output.

---

🧠 Architecture Snapshot

The framework is organized around separation of concerns:

• features/ → business-readable scenarios
• steps/ → step definitions
• pages/ → UI interaction abstraction
• hooks/ → execution lifecycle and evidence handling
• data/ → structured data support
• utilities/ → shared helpers and reusable logic
• principal/ → execution entry points or runner classes

For full architecture details, see:

• docs/ARCHITECTURE.md
• docs/ARCHITECTURE.es.md

---

🔗 Related Project

If you would like to see a related automation project built in another ecosystem, check out:

SauceDemo Playwright Cucumber TypeScript Automation

A related QA automation project implemented with:

• Playwright
• Cucumber
• TypeScript
• Allure Report
• Page Object Model (POM)

This helps demonstrate the same automation mindset across different stacks: Java + Selenium + Cucumber + JUnit 6 in this repository and TypeScript + Playwright + Cucumber in the related one.

---

📚 Documentation Index

Core docs

• docs/COMMANDS.md → Commands reference (English)
• docs/COMMANDS.es.md → Commands reference (Spanish)
• docs/ENVIRONMENT.md → Environment guide (English)
• docs/ENVIRONMENT.es.md → Environment guide (Spanish)
• docs/ARCHITECTURE.md → Architecture guide (English)
• docs/ARCHITECTURE.es.md → Architecture guide (Spanish)

Repository docs

• CHANGELOG.md → Project changelog (English)
• CHANGELOG.es.md → Historial de cambios (Español)
• CONTRIBUTING.md → Contribution guide (English)
• CONTRIBUTING.es.md → Guía de contribución (Español)

---

🛣 Roadmap

• Strengthen CI/CD integration
• Refine reporting and evidence publication
• Clarify runtime parameter handling for browser and execution grouping
• Improve reusable automation modules and data support
• Expand documentation as implementation details evolve

---

👨‍💻 Author

Carlos R.
QA | Test Automation Engineer

🔗 GitHub: https://github.com/CarlosArman

---

⭐ Final Note

This project is intentionally documented and organized to reflect not only test automation capability, but also engineering maturity in QA automation design, including maintainable structure, reporting awareness, documentation discipline, and clear framework evolution.