🌀 Ellithium

🌀 Unified Test Automation Framework for Web, Mobile, API, SQL and NoSQL DBs Testing🚀

Ellithium is a Unified powerful, flexible, and scalable test automation framework designed to streamline and enhance the testing process. Leveraging tools such as TestNG, Cucumber, Rest Assured, and others, it provides an end-to-end solution for automated testing. With support for BDD, cross-browser testing, parallel execution, headless testing, and detailed Allure reporting, Ellithium aims to make your test automation faster, more reliable, and easier to maintain.

Supported Testing PlatForms

Web	Mobile	API	DB
✅	✅	✅	✅

Supported Cloud Mobile Device Test Labs

BrowserStack	LambdaTest	Sauce Labs
✅	✅	✅

Supported DB Types with Caching Mechanisms 🚀

Mongo	Couchebase	Redis	MY_SQL	SQL_SERVER	ORACLE	IBM_DB2	POSTGRES_SQL	SQLITE
✅	✅	✅	✅	✅	✅	✅	✅	✅

Key Features

BDD Support	Parallel Execution	Cross-Browser Testing	Headless Testing	Logging	Automatic Screenshots / Video Recording	User Stories Linking	Reporting
✅	✅	✅	✅	✅	✅	✅	✅

Command line Executor Interface	Synchronization Handling	CI/CD integration	Test Data Generation	Notification System
✅	✅	✅	✅	✅

• Allure Reporting: Generate rich, interactive test reports with Allure, including test history and trend analysis.
• Modular Design: A well-structured and modular framework promoting code reuse and easy maintenance.
• Executing OS Commands: Execute system commands via the built-in Command Executor Interface.
• API Testing: Full support for API testing with Rest Assured for RESTful services.
• Database Testing: Extends coverage to both SQL and NoSQL databases, including MySQL, SQL Server, PostgreSQL, Oracle, IBM DB2, SQLite, Couchbase, MongoDB, and Redis, enabling comprehensive backend testing.
• Mobile Testing: Test native, hybrid, and mobile apps on Android and IOS, with Appium integration and support for real devices and emulators.
• CI/CD Integration: Seamless integration with popular CI/CD tools such as Jenkins, GitHub Actions, and GitLab.
• Cloud Mobile Device Test Labs: Reliable exeuction with cloud platforms such as BrowserStack, LambdaTest, and Sauce Labs with mobile app uploader.
• Automatic Video Recording: Configurable Web and Mobile execution Recording in synchronous and asynchronous modes based on video recording attachment flag.
• Test Data Generation: Dynamically generate test data using Java Faker for realistic names, emails, addresses, and more.
• Email Notifications: Automated SMTP email delivery with rich HTML reports and configurable triggers.
• Slack Integration: Webhook-based notifications with structured messages and channel targeting.
• Exception Handling: Robust mechanisms for capturing exceptions during test execution.

👨‍💻 Supported OS with OS Command Executor Interface for Desktop OS

Windows	Mac	Linux	Android	IOS
✅	✅	✅	✅	✅

📄 Supported File Formats for Reading and Writing

Ellithium supports reading and writing data from various file formats, including:

JSON	CSV	Excel	Properties	Jar	PDF	Text
✅	✅	✅	✅	✅	✅	✅

👨‍💻 Developed using:

🦸 Powered by:

📚 Documentation

For comprehensive documentation and user guides, visit our official documentation site:

• User Guide & Documentation - Complete documentation including:
  • Detailed setup instructions
  • Framework architecture
  • API documentation
  • Best practices
  • Configuration guides
  • Examples and tutorials

Prerequisites

Ensure you have the following installed:

• Java Development Kit (JDK): 21 preferred
• Maven: 3.8.1 or higher (last version 3.9.9 recommended)

🏁 Getting Started

• Follow these steps to set up a new Maven project with Ellithium: Here is the updated Getting Started section formatted for your README file:

---

Step 1: Create a New Maven Project

• Create a new Maven project using your preferred IDE (e.g., IntelliJ IDEA).

Step 2: Update the pom.xml

• Add the following configuration to your pom.xml to set the Java version, include the required dependencies, and configure the plugins.

<properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <Ellithiumversion>2.3.2</Ellithiumversion>
</properties>
<dependencies>
<dependency>
    <groupId>io.github.abdelrhman-ellithy</groupId>
    <artifactId>ellithium</artifactId>
    <version>${Ellithiumversion}</version>
</dependency>
</dependencies>
<build>
<plugins>
    <!-- Maven Compiler Plugin -->
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.14.0</version>
        <configuration>
            <source>21</source>
            <target>21</target>
        </configuration>
    </plugin>

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.3</version>
        <configuration>
            <reportsDirectory>${project.build.directory}/surefire-reports</reportsDirectory>
            <testFailureIgnore>true</testFailureIgnore>
            <failIfNoTests>false</failIfNoTests>
            <systemPropertyVariables>
                <testng.dtd.http>true</testng.dtd.http>
            </systemPropertyVariables>
            <failIfNoSpecifiedTests>false</failIfNoSpecifiedTests>
            <trimStackTrace>false</trimStackTrace>
            <useFile>false</useFile>
            <encoding>UTF-8</encoding>
            <properties>
                <property>
                    <name>listener</name>
                    <value>Ellithium.core.execution.listener.CustomTestNGListener</value>
                </property>
            </properties>
        </configuration>
    </plugin>

    <!-- Exec Maven Plugin -->
    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.5.0</version>
        <executions>
            <execution>
                <id>intialize</id>
                <phase>initialize</phase>
                <goals>
                    <goal>java</goal>
                </goals>
                <configuration>
                    <mainClass>Ellithium.core.execution.Internal.Loader.StartUpLoader</mainClass>
                    <includePluginDependencies>true</includePluginDependencies>
                    <classpathScope>compile</classpathScope>
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>
<resources>
    <resource>
        <directory>src/main/resources/properties</directory>
        <includes>
            <include>**/*</include>
        </includes>
    </resource>
</resources>
</build>

Step 3: Open the Termenal in the Project directory then run this command

mvn clean test

Option 1: BDD Mode With Cucumber

• Demo-Project for setup use after follow the following steps

Step 1: Create a Test Runner Class

• Create a Runner Package then create a new class named TestRunner that extends the BDDSetup class from Ellithium.
• Specify the paths for your feature files and step definitions using the @CucumberOptions.

package Runner;

import Ellithium.core.base.BDDSetup;
import io.cucumber.testng.CucumberOptions;

@CucumberOptions(
        glue = "stepDefinitions", // path to your stepDefinitions package, note you should use . instead of /
        features = "src/main/resources/features" // path to your features folder
        , tags = "@Run"
)
public class TestRunner extends BDDSetup {
}

Step 2: To Create a BaseStepDefinitions Class.

• Create a BaseStepDefinitions class that will be used to extend the other StepDefinitions Classes from it.

package Base;

import Ellithium.core.driver.DriverFactory;
import org.openqa.selenium.WebDriver;

public class BaseStepDefinitions {
    protected WebDriver driver;

    protected AndroidDriver androidDriver;
    protected IOSDriver iosDriver;

    public BaseStepDefinitions() {


        // for Local Machine Web Execution
        driver= DriverFactory.getNewLocalDriver(LocalDriverType.Chrome, HeadlessMode.False, PrivateMode.True, PageLoadStrategyMode.Normal,WebSecurityMode.SecureMode,SandboxMode.Sandbox);

        // for Remote Machine Web Execution
        driver= DriverFactory.getNewRemoteDriver(RemoteDriverType.Remote_Chrome,new URL("http://localhost:4723"),capabilities, HeadlessMode.False, PrivateMode.True, PageLoadStrategyMode.Normal,WebSecurityMode.SecureMode,SandboxMode.Sandbox);

        // for Android Mobile
        androidDriver= DriverFactory.getNewMobileDriver(MobileDriverType.Android,new URL("http://localhost:4723"),options);
        
        // for IOS Mobile
        iosDriver=DriverFactory.getNewMobileDriver(MobileDriverType.IOS,new URL("http://localhost:4723"),options);
        

        // using config builder (after release 2.03)

        DriverConfigBuilder driverConfig=new LocalDriverConfig(LocalDriverType.Chrome, // same for RemoteDriverConfig, MobileDriverConfig
                HeadlessMode.False, PrivateMode.False,
                PageLoadStrategyMode.Normal,
                WebSecurityMode.SecureMode,
                SandboxMode.Sandbox);
        driver=DriverFactory.getNewDriver(driverConfig);

        // for DB SQL Provider [MY_SQL, SQL_SERVER, POSTGRES_SQL, ORACLE_SID, ORACLE_SERVICE_NAME, IBM_DB2]
       SQLDatabaseProvider db=new SQLDatabaseProvider(
                SQLDBType.MY_SQL,
                username,
                password,
                serverIp,
                port,
                dbName);
    }
        // for DB SQL Provider [SQLite]
        SQLDatabaseProvider SQLitedb= SQLDatabaseProvider( SQLDBType.SQLITE, pathToSQLiteDataBase);

        // for NoSQL DB Provider
        CouchbaseDatabaseProvider couchDB=CouchbaseDatabaseProvider(connectionString,  username,  password,  bucketName);
        MongoDatabaseProvider mongoDB=MongoDatabaseProvider( connectionString,  dbName);
        RedisDatabaseProvider redisDB=RedisDatabaseProvider( connectionString);
    }
}

• The default values for WebDriver if you didn't pass all the paramaters are:

    @default("false") String HeadlessMode,      // can be true or false (Not Supported with Safari)
    @default("Normal") String PageLoadStrategy, // can be Normal or Eager
    @default("False") String PrivateMode,        // can be true or false
    @default("Sandbox") String SandboxMode,     // can be Sandbox or NoSandbox (Not Supported with Safari)
    @default("True") String WebSecurityMode     // can be True or False (Not Supported with Safari)

Option 2: default Mode

• Demo-Project for setup use after follow the following steps

Step 1: Create a BaseTest Class

• Create a UI_BDD Package then create a new class named BaseTest that extends the NonBDDSetup class from Ellithium.

package UI_NonBDD;

import Ellithium.core.driver.DriverFactory;
import Ellithium.core.base.NonBDDSetup;
import org.openqa.selenium.WebDriver;
import org.testng.annotations.*;

public class BaseTests {
    WebDriver driver;

    // with Web and the Same Logic for Other
    @BeforeClass
    public void Setup() {

        
        // for Local Machine Web Execution
        driver = DriverFactory.getNewLocalDriver(LocalDriverType.Chrome, HeadlessMode.False, PrivateMode.True, PageLoadStrategyMode.Normal, WebSecurityMode.SecureMode, SandboxMode.Sandbox);

        // for Remote Machine Web Execution
        driver = DriverFactory.getNewRemoteDriver(RemoteDriverType.Remote_Chrome, new URL("http://localhost:4723"), capabilities, HeadlessMode.False, PrivateMode.True, PageLoadStrategyMode.Normal, WebSecurityMode.SecureMode, SandboxMode.Sandbox);

        // for Android Mobile
        androidDriver = DriverFactory.getNewMobileDriver(MobileDriverType.Android, new URL("http://localhost:4723"), options);

        // for IOS Mobile
        iosDriver = DriverFactory.getNewMobileDriver(MobileDriverType.IOS, new URL("http://localhost:4723"), options);

        // for DB SQL Provider [MY_SQL, SQL_SERVER, POSTGRES_SQL, ORACLE_SID, ORACLE_SERVICE_NAME, IBM_DB2]
        SQLDatabaseProvider db = new SQLDatabaseProvider(
                SQLDBType.MY_SQL,
                username,
                password,
                serverIp,
                port,
                dbName);

        
        // using config builder (after release 2.03)

        DriverConfigBuilder driverConfig=new LocalDriverConfig(LocalDriverType.Chrome, // same for RemoteDriverConfig, MobileDriverConfig
                HeadlessMode.False, PrivateMode.False,
                PageLoadStrategyMode.Normal,
                WebSecurityMode.SecureMode,
                SandboxMode.Sandbox);
        driver=DriverFactory.getNewDriver(driverConfig);

    }

    // for DB SQL Provider [SQLite]
    SQLDatabaseProvider SQLitedb = SQLDatabaseProvider(SQLDBType.SQLITE, pathToSQLiteDataBase);

    // for NoSQL DB Provider
    CouchbaseDatabaseProvider couchDB = CouchbaseDatabaseProvider(connectionString, username, password, bucketName);
    MongoDatabaseProvider mongoDB = MongoDatabaseProvider(String connectionString, String dbName);
    RedisDatabaseProvider redisDB = RedisDatabaseProvider(String connectionString);
}

    @AfterClass
    public void tareDown() {
        DriverFactory.quitDriver();
    }
}

• Complete your logic as you like here after that
• this class will be used to extend the other classes from it
• as here in step 2

Step 2: Create a another Test Class and extend from the BaseTests class

package UI_BDD;

import Base.BaseTests;
import Ellithium.Utilities.assertion.AssertionExecutor;
import Pages.LoginPage;
import org.testng.annotations.DataProvider;
import org.testng.annotations.Test;

public class loginTests extends BaseTests {
    @DataProvider(name = "invalidLoginData")
    Object[][] getInvalidTestData() {
        return new Object[][]{
                {"tomsmith", "hamada", "Your password is invalid"},
                {"hamada", "SuperSecretPassword!", "Your username is invalid"}
        };
    }

    LoginPage login;

    @Test(priority = 1, dataProvider = "invalidLoginData")
    public void invalidLogin(String username, String password, String expectedMessage) {
        login = home.clickFormAuthentication();
        login.setUserName(username);
        login.setPassword(password);
        var secureAreaPage = login.clickLoginBtn();
        String actualMessage = secureAreaPage.getLoginMassega();
        AssertionExecutor.hard.assertTrue(actualMessage.contains(expectedMessage));
    }

    @Test(priority = 2)
    public void validLogin() {
        login = home.clickFormAuthentication();
        login.setPassword("SuperSecretPassword!");
        login.setUserName("tomsmith");
        var secureAreaPage = login.clickLoginBtn();
        String actualMessage = secureAreaPage.getLoginMassega();
        String expectedMessage = "You logged into a secure area!";
        AssertionExecutor.hard.assertTrue(actualMessage.contains(expectedMessage));
    }
}

Step 3: Use Driver Actions Class to Perform actions on Web and Mobile, as It handles many steps and syncronization

package Pages;

import Ellithium.Utilities.interactions.DriverActions;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
public class LoginPage {
    WebDriver driver;
    DriverActions driverActions;
    public LoginPage(WebDriver driver) {
        this.driver=driver;
        driverActions=new DriverActions(driver);
    }
    public void setUserName(String username){
        //                     locator,         data      , timeout, polling time 
        driverActions.elements().sendData(By.id("username"),username, 5,           200);
    }
    public void setPassword(String password){
        //                     locator,         data      , timeout
        driverActions.elements().sendData(By.id("password"),password, 5);
    }
    public SecureAreaPage clickLoginBtn(){
                //                     locator
        driverActions.elements().clickOnElement(By.tagName("button"));
        return new SecureAreaPage(driver);
    }

}

This should cover the steps to get your Ellithium framework up and running in a new Maven project.

📬 Contact

• For questions, suggestions, or feedback, feel free to reach out to Abdelrahman Ellithy at [email protected].

---