Practical Automation Template: Using SHAFT_Engine

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

🚀 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

Clone the repository:

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

Build the project:
```
mvn clean compile
```
Install dependencies:
```
mvn clean install -DskipTests
```

Verify installation:

mvn test -Dtest=TestClass#navigateToDuckDuckGoAndAssertBrowserTitleIsDisplayedCorrectly

IDE Setup (IntelliJ IDEA Recommended)

Import the project as a Maven project
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:

Check existing issues
Review the documentation
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

Start Here: Run the sample tests in this template
Next: Explore the Getting Started Guide
Advanced: Check out Best Practices
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

Fork this repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Name		Name	Last commit message	Last commit date
.github		.github
.idea		.idea
src		src
.gitignore		.gitignore
README.md		README.md
pom.xml		pom.xml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation