SHAFT_ENGINE

<!--
  SHAFT Engine — Unified Java Test Automation Framework
  Keywords: Java test automation, Selenium WebDriver, Appium mobile testing, REST Assured API testing,
  cross-browser testing, BDD Cucumber, TestNG, JUnit 5, test framework, open source,
  fluent API, GUI automation, mobile automation, web testing, API testing, database testing,
  CLI testing, parallel testing, Allure reporting, BrowserStack, LambdaTest, Docker CI/CD,
  Flutter testing, accessibility testing, visual testing, OpenCV, smart locators, SHAFT_ENGINE
-->
<a id="top"></a>
<div align="center">

<h1>
<picture>
  <source srcset="https://github.com/user-attachments/assets/b2e8454d-97ed-4dd8-91f2-1c09c53ba94e" media="(prefers-color-scheme: light)" width="40"/>
  <source srcset="https://github.com/user-attachments/assets/9cb4a7a8-2de7-486c-adb1-ad254af8c58b"  media="(prefers-color-scheme: dark)" width="40"/>
  <img src="https://github.com/user-attachments/assets/016ebb3c-4090-4f07-a9b3-830fdf4cb696" alt="SHAFT Engine Logo"/>
</picture> SHAFT : Unified Test Automation Engine
</h1>

**Stop reinventing the wheel.** Write your tests once and run them everywhere — across browsers, devices, and APIs — with a single, fluent Java framework.

SHAFT Engine is an open-source **Java test automation framework** built on top of [Selenium](https://www.selenium.dev/), [Appium](https://appium.io/), and [REST Assured](https://rest-assured.io/). It provides a unified, fluent API for **cross-browser testing**, **mobile app testing**, **API testing**, **CLI testing**, and **database testing** — so you can automate anything, from any platform, with zero boilerplate.

[![GitHub Stars](https://img.shields.io/github/stars/ShaftHQ/SHAFT_ENGINE?style=for-the-badge&logo=github&label=Stars&color=gold)](https://github.com/ShaftHQ/SHAFT_ENGINE/stargazers)
[![Maven Central](https://img.shields.io/maven-central/v/io.github.shafthq/shaft-engine?style=for-the-badge&logo=apachemaven&label=Maven%20Central&color=indigo)](https://central.sonatype.com/artifact/io.github.shafthq/shaft-engine)
[![License](https://img.shields.io/github/license/ShaftHQ/SHAFT_Engine?color=indigo&style=for-the-badge)](https://github.com/ShaftHQ/SHAFT_ENGINE/blob/main/LICENSE)
[![E2E Tests](https://img.shields.io/github/actions/workflow/status/SHAFTHQ/SHAFT_Engine/e2eTests.yml?branch=main&color=forestgreen&label=E2E%20Tests&style=for-the-badge)](https://github.com/ShaftHQ/SHAFT_ENGINE/actions/workflows/e2eTests.yml)
[![Code QL](https://img.shields.io/github/actions/workflow/status/SHAFTHQ/SHAFT_Engine/codeql-analysis.yml?branch=main&label=Security&color=forestgreen&style=for-the-badge)](https://github.com/ShaftHQ/SHAFT_ENGINE/actions/workflows/codeql-analysis.yml)
[![Code Quality](https://img.shields.io/codacy/grade/4d6d48aba396411fa3170184330ba089?style=for-the-badge&color=blue&label=Code%20Quality)](https://app.codacy.com/gh/ShaftHQ/SHAFT_ENGINE/dashboard)
[![Codecov](https://img.shields.io/codecov/c/github/shafthq/shaft_engine?style=for-the-badge&label=Coverage&color=blue)](https://app.codecov.io/gh/ShaftHQ/SHAFT_ENGINE)
[![Contributors](https://img.shields.io/github/contributors/ShaftHQ/SHAFT_ENGINE?color=indigo&style=for-the-badge)](https://github.com/ShaftHQ/SHAFT_ENGINE/graphs/contributors)

<a href="https://techforpalestine.org/learn-more" target="_blank"><img alt="Tech for Palestine - Ceasefire Now" src="https://img.shields.io/badge/%F0%9F%87%B5%F0%9F%87%B8_Ceasefire_Now-techforpalestine.org-000000?style=for-the-badge&label=Ceasefire%20Now&color=D83838"></a>

---

### 🏆 Recognition & Trust

<table border="0" align="center">
 <tr>
  <td align="center" valign="top">
   <b>Fully Documented</b><br/><br/>
   <a href="https://ShaftHQ.github.io/"><img width="280" alt="SHAFT Engine User Guide and Documentation" src="https://github.com/ShaftHQ/SHAFT_ENGINE/assets/19201898/bdd6db98-4121-4a86-b7db-fb94b8830d11"></a>
  </td>
  <td align="center" valign="top">
   <b>Award Winning</b><br/><br/>
   <a href="https://opensource.googleblog.com/2023/05/google-open-source-peer-bonus-program-announces-first-group-of-winners-2023.html"><img width="230" alt="Google Open Source Peer Bonus Award Winner 2023" src="https://github.com/user-attachments/assets/a21a9e31-c63d-4712-bd9d-2bd131e5173c"/></a>
  </td>
  <td align="center" valign="top">
   <b>Selenium Ecosystem</b><br/><br/>
   <a href="https://www.selenium.dev/ecosystem/#frameworks"><img width="280" alt="Official Selenium Ecosystem Framework" src="https://github.com/ShaftHQ/SHAFT_ENGINE/assets/19201898/b13d4c2c-72ce-4de6-861f-d143f905c5ab"></a>
  </td>
 </tr>
</table>

</div>

---

## 📖 Table of Contents

- [🚀 Why SHAFT?](#-why-shaft)
- [💡 See the Difference](#-see-the-difference)
- [⚡ Quick Start](#-quick-start)
- [⬆️ Preferred automated upgrade](docs/UPGRADING_TO_MODULAR_SHAFT.md)
- [🧭 Allure CLI Version Enforcement (Opt-in)](#-allure-cli-version-enforcement-opt-in)
- [✨ Key Features](#-key-features)
- [🌍 Success Partners](#-success-partners)
- [📚 Documentation](#-documentation)
- [🤝 Community & Support](#-community--support)
- [💖 Sponsor](#-sponsor)
- [📜 License](#-license)

---

## 🚀 Why SHAFT?

If you're tired of managing a fragile patchwork of Selenium helpers, custom wrappers, and retry logic — you're not alone. **SHAFT Engine** replaces all of that with a single, battle-tested framework trusted by **41,000+ engineers** across **10+ countries**.

Built on industry-standard technologies — [Selenium](https://www.selenium.dev/), [Appium](https://appium.io/), and [REST Assured](https://rest-assured.io/) — SHAFT gives you a fluent, chainable API that works across **web browsers**, **mobile apps**, **REST APIs**, **databases**, and **CLIs**. No more boilerplate. No more flaky tests. Just results.

### What Makes SHAFT Different?

| Feature                      | What You Get                                                                                                                                                                                                                   |
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 🎯 **Unified API**           | One fluent syntax for Web, Mobile, API, CLI, and Database testing                                                                                                                                                              |
| 🔧 **Zero Boilerplate**      | Smart auto-configuration — no WebDriverManager, no manual waits, no setup code                                                                                                                                                 |
| 📊 **Rich Reporting**        | Built-in [Allure](https://allurereport.org/) integration with screenshots and detailed logs, plus provider-native or optional desktop video                                                                                    |
| 🤖 **AI-Powered Validation** | Optional `shaft-visual` module for [OpenCV](https://opencv.org/), Applitools Eyes, Shutterbug, and image-based element detection                                                                                               |
| 🌐 **Cloud-Ready**           | Direct [BrowserStack](https://www.browserstack.com/), [LambdaTest](https://www.testmuai.com/?utm_medium=sponsor&utm_source=shaft-engine), and Selenium Grid support in `shaft-engine`; optional BrowserStack SDK orchestration |
| ⚙️ **Any Test Runner**       | Works with [TestNG](https://testng.org/), [JUnit 5](https://junit.org/junit5/), and [Cucumber](https://cucumber.io/) out of the box                                                                                            |
| 🐳 **Containerized**         | Ready-to-use Docker support for CI/CD pipelines                                                                                                                                                                                |
| 📱 **Full Mobile**           | Native, Hybrid, and [Flutter](https://flutter.dev/) apps on Android & iOS via [Appium](https://appium.io/)                                                                                                                     |

---

## 💡 See the Difference

Stop writing dozens of lines of brittle Selenium boilerplate. Here's what SHAFT looks like compared to raw Selenium:

<table>
<tr>
<td>

**❌ Raw Selenium (verbose & fragile)**

</td>
<td>

**✅ SHAFT Engine (clean & reliable)**

</td>
</tr>
<tr>
<td>

```java
WebDriver driver = new ChromeDriver();
driver.get("https://example.com");
WebDriverWait wait =
    new WebDriverWait(driver, Duration.ofSeconds(10));
WebElement el = wait.until(
    ExpectedConditions.visibilityOfElementLocated(
        By.name("q")));
el.sendKeys("SHAFT");
el.sendKeys(Keys.ENTER);
String title = driver.getTitle();
Assert.assertTrue(title.contains("SHAFT"));
driver.quit();
```

</td>
<td>

```java
SHAFT.GUI.WebDriver driver =
    new SHAFT.GUI.WebDriver();
driver.browser().navigateToURL("https://example.com")
  .and().element().type(By.name("q"),
      "SHAFT" + Keys.ENTER)
  .and().assertThat().title()
      .contains("SHAFT");
driver.quit();
```

</td>
</tr>
</table>

> **Fewer lines. Automatic synchronization. Built-in assertions. Beautiful reports.** That's SHAFT.

---

## ⚡ Quick Start

Get up and running in under 5 minutes!

### Option 1: Interactive Project Generator 🎉 *(Recommended)*
The fastest way to create a new SHAFT project with a user-friendly web UI:

👉 **[Launch Project Generator](https://shaftengine.netlify.app/docs/Getting_Started/first_steps_5#option-1-interactive-project-generator-recommended)**

Choose your test runner (TestNG / JUnit 5 / Cucumber), select your platform (Web / Mobile / API), and download a ready-to-use project — complete with CI/CD configuration.

### Option 2