Practical Automation Template: Using SHAFT_Engine

A powerful, ready-to-use template for starting your end-to-end test automation with SHAFT_Engine.

---

Table of Contents

• 🚀 Project Overview and Motivation
• ⚡ Getting Started (Prerequisites and Dependencies)
• 📁 Project Structure Breakdown (Critical Requirement)
• 🎯 Usage and Running Tests
• 📸 Visual Demonstration (The Viral Component)
• 🆘 Support and Documentation
• 🤝 Contributing and License

---

🚀 Project Overview and Motivation

This repository is a production-ready starter kit for SHAFT_Engine users, eliminating setup overhead and providing hands-on experience with core features—including Web, Mobile, API, and Database testing. SHAFT_Engine empowers engineers to write highly readable code, benefit from built-in reporting and logging, and leverage a unified API across multiple testing technologies.

Why Choose SHAFT_Engine?

• 🔧 Unified API for Web, Mobile, API, and Database testing
• 📊 Built-in reporting with Allure integration and detailed logs
• 📖 Highly readable and maintainable test code
• ⚡ Zero configuration - works out of the box
• 🌐 Cross-browser support with Selenium Grid integration
• 📈 CI/CD ready with GitHub Actions workflow included

Real-World Impact:

• Reduce test automation setup time from days to minutes
• Write maintainable tests that serve as living documentation
• Scale across multiple browsers and environments effortlessly

---

⚡ Getting Started (Prerequisites and Dependencies)

Prerequisites

• Java Development Kit (JDK) 21+ (recommended JDK 24 for latest features)
• Apache Maven 3.6.3+
• Modern IDE (e.g., IntelliJ IDEA, Eclipse, VS Code with Java extensions)
• Docker (optional, for Selenium Grid testing)

Quick Installation

1. Clone the repository:

   git clone https://github.com/ShaftHQ/using_SHAFT_Engine.git
   cd using_SHAFT_Engine

2. Build the project:

   mvn clean compile

3. Install dependencies:

   mvn clean install -DskipTests

4. Verify installation:

   mvn test -Dtest=TestClass#navigateToDuckDuckGoAndAssertBrowserTitleIsDisplayedCorrectly

IDE Setup (IntelliJ IDEA Recommended)

1. Import the project as a Maven project
2. Ensure the Project SDK is set to JDK 21+

---

📁 Project Structure Breakdown

using_SHAFT_Engine/
├── 📄 pom.xml                                    # Maven build configuration
├── 📁 src/
│   ├── 📁 main/
│   │   └── 📁 resources/
│   │       └── 📁 properties/                    # 🔧 Configuration hub
│   │           ├── 📄 custom.properties          # Custom configurations
│   │           ├── 📄 log4j2.properties          # Logging configuration
│   │           ├── 📄 TestNG.properties          # TestNG runner settings
│   │           ├── 📄 cucumber.properties        # Cucumber integration
│   │           ├── 📄 reportportal.properties    # ReportPortal integration
│   │           └── 📁 default/                   # Default configuration fallbacks
│   └── 📁 test/
│       ├── 📁 java/
│       │   └── 📁 testPackage/
│       │       └── 📄 TestClass.java            # 🧪 Sample test implementation
│       └── 📁 resources/
│           ├── 📁 testDataFiles/                # 📊 Test data storage
│           │   └── 📄 simpleJSON.json          # JSON test data
│           └── 📁 META-INF/
│               └── 📁 services/                 # Service configurations for listeners
├── 📁 .github/
│   └── 📁 workflows/
│       ├── 📄 e2etests.yml                     # 🚀 CI/CD pipeline configuration
│       └── 📄 sync-template.yml                # 🔄 Automated template sync
└── 📁 target/                                   # 📈 Generated reports and artifacts
    ├── 📁 logs/                                # Detailed execution logs
    ├── 📁 surefire-reports/                   # TestNG/JUnit reports
    └── 📄 allure-report/                      # Rich HTML reports

Key Components Explained

Component	Purpose	Impact
pom.xml	Dependencies, plugins, and build profiles	Central project configuration
TestClass.java	Sample web automation tests using SHAFT_Engine API	Living documentation of framework capabilities
properties/	Runtime configurations for different environments	Zero-code environment switching
testDataFiles/	External test data (JSON, CSV, Excel)	Data-driven testing support
e2etests.yml	Multi-browser CI/CD pipeline	Automated testing across Chrome, Firefox, Edge
sync-template.yml	Automated template synchronization	Keeps repository files in sync with template

---

🎯 Usage and Running Tests

Sample Test Code Walkthrough

Here's the actual test code included in this template:

package testPackage;

import com.shaft.driver.SHAFT;
import com.shaft.gui.internal.locator.Locator;
import org.openqa.selenium.By;
import org.openqa.selenium.Keys;
import org.testng.annotations.*;

public class TestClass {
    SHAFT.GUI.WebDriver driver;
    SHAFT.TestData.JSON testData;

    String targetUrl = "https://duckduckgo.com/";

    // SHAFT's fluent locator API - more readable than traditional By locators
    By logo = By.xpath("//div[contains(@class,'container_fullWidth__1H_L8')]//img");
    By searchBox = Locator.hasAnyTagName().hasAttribute("name", "q").build();
    By firstSearchResult = Locator.hasTagName("article").isFirst().build();

    @Test
    public void navigateToDuckDuckGoAndAssertBrowserTitleIsDisplayedCorrectly() {
        // Fluent API with built-in reporting and error handling
        driver.browser().navigateToURL(targetUrl)
                .and().assertThat().title().contains(testData.getTestData("expectedTitle"));
    }

    @Test
    public void navigateToDuckDuckGoAndAssertLogoIsDisplayedCorrectly() {
        // Visual regression testing built-in
        driver.browser().navigateToURL(targetUrl)
                .and().element().assertThat(logo).matchesReferenceImage();
    }

    @Test
    public void searchForQueryAndAssert() {
        // Data-driven testing with JSON files
        driver.browser().navigateToURL(targetUrl)
                .and().element().type(searchBox, testData.getTestData("searchQuery") + Keys.ENTER)
                .and().assertThat(firstSearchResult).text()
                .doesNotEqual(testData.getTestData("unexpectedInFirstResult"));
    }

    @BeforeClass
    public void beforeClass() {
        // Load test data from JSON file
        testData = new SHAFT.TestData.JSON("simpleJSON.json");
    }

    @BeforeMethod
    public void beforeMethod() {
        // Create new driver instance for each test
        driver = new SHAFT.GUI.WebDriver();
    }

    @AfterMethod
    public void afterMethod() {
        // Automatic cleanup
        driver.quit();
    }
}

Running Tests - Multiple Options

1. Basic Test Execution

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=TestClass

# Run specific test method
mvn test -Dtest=TestClass#navigateToDuckDuckGoAndAssertBrowserTitleIsDisplayedCorrectly

2. Multi-Browser Testing (Local)

# Chrome (default)
mvn test -DtargetBrowserName=chrome

# Firefox
mvn test -DtargetBrowserName=firefox

# Microsoft Edge
mvn test -DtargetBrowserName=edge

# Headless execution
mvn test -DheadlessExecution=true

3. Selenium Grid / Docker Integration

# Download and start Selenium Grid
curl -o docker-compose.yml https://raw.githubusercontent.com/SeleniumHQ/docker-selenium/trunk/docker-compose-v3.yml
docker compose up --scale chrome=2 --scale firefox=2 -d

# Run tests against Grid
mvn test -DexecutionAddress=localhost:4444 -DtargetBrowserName=chrome

4. Advanced Configuration Options

# Parallel execution with custom threads
mvn test -DsetParallel=METHODS -DsetParallelMode=DYNAMIC -DthreadCount=3

# Generate Allure reports
mvn test -DgenerateAllureReportArchive=true

# Retry failed tests
mvn test -DretryMaximumNumberOfAttempts=2

# Custom test data environment
mvn test -DtestDataFolderPath=src/test/resources/testDataFiles/

Test Data Management

The template includes a JSON-based test data system:

{
  "searchQuery": "SHAFT_Engine",
  "expectedTitle": "DuckDuckGo", 
  "unexpectedInFirstResult": "Nope"
}

Accessing test data in your tests:

// In @BeforeClass
testData = new SHAFT.TestData.JSON("simpleJSON.json");

// In test methods
String query = testData.getTestData("searchQuery");

---

📸 Visual Demonstration

🎬 Live Test Execution Demo

Coming Soon: Dynamic GIF showing a complete test run from execution to final HTML report generation.

📊 Rich HTML Reports

SHAFT_Engine generates comprehensive reports automatically:

• Allure Reports: Interactive HTML reports with step-by-step screenshots
• TestNG Reports: Detailed execution summaries
• Custom Logs: Structured logging with different levels
• Screenshots: Automatic capture on failures and assertions

🔄 CI/CD Pipeline Visualization

The included GitHub Actions workflow provides:

• ✅ Multi-browser testing (Chrome, Firefox, Edge)
• 🐳 Dockerized Selenium Grid
• 📈 Automatic report generation and archiving
• 🔄 Parallel execution across browser matrix
• 📊 Test summaries and artifact uploads

---

🆘 Support and Documentation

Official Resources

• 📚 SHAFT_Engine Documentation - Complete API reference and guides
• 🐛 Report Issues - Bug reports and feature requests
• 💬 Discussions - Community support and Q&A
• 📖 Wiki - Advanced tutorials and best practices

Quick Support Guide

Before Opening an Issue:

1. Check existing issues
2. Review the documentation
3. Try the troubleshooting guide

When Opening an Issue, Include:

• SHAFT_Engine version (mvn dependency:tree | grep SHAFT)
• Java version (java -version)
• Operating System and Browser versions
• Complete error stack trace
• Minimal reproducible test case

Learning Path

1. Start Here: Run the sample tests in this template
2. Next: Explore the Getting Started Guide
3. Advanced: Check out Best Practices
4. Expert: Contribute to the SHAFT_Engine Core

---

🤝 Contributing and License

How to Contribute

We welcome contributions from the community! Here's how you can help:

🌟 Ways to Contribute

• 🐛 Report Bugs: Found something broken? Open an issue
• 💡 Suggest Features: Have ideas for improvements? Start a discussion
• 📝 Improve Documentation: Fix typos, add examples, or write guides
• 🧪 Add Tests: Expand the test coverage with new examples
• 🔧 Code Contributions: Implement new features or fix bugs

🚀 Quick Contribution Guide

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📋 Contribution Guidelines

• Follow existing code style and conventions
• Add tests for new functionality
• Update documentation for any API changes
• Ensure all tests pass before submitting
• Write clear commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License - Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...

🙏 Acknowledgments

• SHAFT_Engine Team for creating this amazing framework
• Contributors who help improve this template
• Community members who provide feedback and support

---

Ready to revolutionize your test automation?

⭐ Star this repository • 🍴 Fork and customize • 📖 Read the docs

Built with ❤️ by the SHAFT_Engine community