# karimelkomy/python-test-automation-framework architecture

> Architecture diagram of the GitHub repository karimelkomy/python-test-automation-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karimelkomy/python-test-automation-framework
- Repository: https://github.com/karimelkomy/python-test-automation-framework

## Overview

##### Project type and purpose
- This is a Python-based Selenium Test Automation Framework built around the Page Object Model.
- Primary use cases: writing UI tests, generating Allure reports, and updating TestRail statuses automatically.

##### Main architectural components
- Test Runner Layer (tests/, conftest.py)
- pytest-based test scripts with decorators for Allure and TestRail.
- Fixture & WebDriver Layer (conftest.py → base/webdriverfactory.py → base/selenium_driver.py)
- Creates, configures, and tears down browser sessions.
- BasePage Layer (base/basepage.py)
- Provides common actions (click, sendKeys, locator resolution).
- Page Object & Navigation Layer (pages/, navigation/)
- pages/: classes for each page’s actions and verifications (LoginPage, DashboardPage, etc.).
- navigation/: shared navigation flows (e.g., goToLoginPage).
- Locator & Test Data Layer (locators/, test_data/)
- locators/locators.json: element definitions (pageName, locator, method).
- test_data/test_data.json & testData.py: environment, credentials, inputs.
- Utilities Layer (utilities/)
- custom_logger.py, read_json.py, read_excel.py, locators_read.py, teststatus.py, util.py.
- Logging, data readers, pass/fail marking, TestRail API calls.
- Reporting & Integration
- Allure: test-step reporting via pytest plugin.
- TestRail: test status updates via testrail.cfg and pytest flag.
- External Dependencies
- Browsers (managed by Selenium WebDriver).
- pytest, JSON/Excel libraries.
- CI/CD (CodeShip) – optional.

##### Component interactions & data flow
- Test Runner invokes pytest tests →
↳ conftest fixtures instantiate WebDriver via WebDriverFactory → SeleniumDriver → Browser
↳ Tests call Navigation/Page classes → BasePage methods → SeleniumDriver → Browser actions
↳ Page & Navigation classes read locators from locators.json and test data from test_data.json
↳ Utilities record logs and mark pass/fail via teststatus → optionally call TestRail API
↳ pytest writes results → Allure plugin generates HTML reports

##### Key architectural patterns & principles
- Page Object Model: separation of test logic from UI operations.
- Single Responsibility: each module has a focused role.
- Data-driven design: external JSON for locators and test data.
- Pluggable integrations: easily add or remove reporting/TestRail/CI.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Test Runner Layer
    subgraph "Test Runner Layer"
        TR["pytest Test Runner"]:::runner
        CON["conftest.py"]:::runner
        TEST1["test_login.py"]:::runner
        TEST2["test_suite_demo.py"]:::runner
    end

    %% Fixture & WebDriver Layer
    subgraph "Fixture & WebDriver Layer"
        WFF["WebDriverFactory"]:::core
        SD["SeleniumDriver"]:::core
        BROWSER["Browser (WebDriver)"]:::external
    end

    %% BasePage Layer
    subgraph "BasePage Layer"
        BP["BasePage"]:::core
    end

    %% Page Object & Navigation Layer
    subgraph "Page Object Layer"
        LP["LoginPage"]:::core
        DP["LoggedInPage"]:::core
    end
    subgraph "Navigation Layer"
        NAV["homeNavigation"]:::core
    end

    %% Locator & Test Data Layer
    subgraph "Locator Module"
        LOC["locators.json"]:::data
    end
    subgraph "Test Data Module"
        TDJ["test_data.json"]:::data
        TDP["testData.py"]:::data
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        CU["custom_logger.py"]:::utils
        LR["locators_read.py"]:::utils
        RJ["read_json.py"]:::utils
        RE["read_excel.py"]:::utils
        TS["teststatus.py"]:::utils
        UT["util.py"]:::utils
    end

    %% Reporting & Integration
    subgraph "Reporting & Integration"
        ALLURE["Allure Reporter"]:::integration
        TRCFG["testrail.cfg"]:::integration
        REQ["requirements.txt"]:::integration
        TESTRAIL["TestRail API"]:::integration
    end

    %% Connections
    TR -->|invokes fixtures| CON
    TR -->|runs| TEST1
    TR -->|runs| TEST2
    CON -->|uses| WFF
    WFF -->|creates session| SD
    SD -->|manages| BROWSER
    TEST1 -->|calls| LP
    TEST2 -->|calls| DP
    LP -->|extends| BP
    DP -->|extends| BP
    BP -->|uses| SD
    LP -->|reads locators| LOC
    DP -->|reads locators| LOC
    LP -->|reads data| TDJ
    DP -->|reads data| TDJ
    NAV -->|shared flows| LP
    NAV -->|shared flows| DP
    UTILALL[Utilities]:::utils
    UTILALL --> CU
    UTILALL --> LR
    UTILALL --> RJ
    UTILALL --> RE
    UTILALL --> TS
    UTILALL --> UT
    TS -->|updates status| TESTRAIL
    TR -->|reports to| ALLURE
    CON -->|reads config| TRCFG
    TR -->|installs deps| REQ

    %% External
    BROWSER:::external

    %% Click Events
    click TR "https://github.com/karimelkomy/python-test-automation-framework/tree/master/tests/"
    click CON "https://github.com/karimelkomy/python-test-automation-framework/blob/master/tests/conftest.py"
    click TEST1 "https://github.com/karimelkomy/python-test-automation-framework/blob/master/tests/test_login.py"
    click TEST2 "https://github.com/karimelkomy/python-test-automation-framework/blob/master/tests/test_suite_demo.py"
    click WFF "https://github.com/karimelkomy/python-test-automation-framework/blob/master/base/webdriverfactory.py"
    click SD "https://github.com/karimelkomy/python-test-automation-framework/blob/master/base/selenium_driver.py"
    click BP "https://github.com/karimelkomy/python-test-automation-framework/blob/master/base/basepage.py"
    click LP "https://github.com/karimelkomy/python-test-automation-framework/blob/master/pages/login_page.py"
    click DP "https://github.com/karimelkomy/python-test-automation-framework/blob/master/pages/loggedin_page.py"
    click NAV "https://github.com/karimelkomy/python-test-automation-framework/blob/master/navigation/homeNavigation.py"
    click LOC "https://github.com/karimelkomy/python-test-automation-framework/blob/master/locators/locators.json"
    click TDJ "https://github.com/karimelkomy/python-test-automation-framework/blob/master/test_data/test_data.json"
    click TDP "https://github.com/karimelkomy/python-test-automation-framework/blob/master/test_data/testData.py"
    click CU "https://github.com/karimelkomy/python-test-automation-framework/blob/master/utilities/custom_logger.py"
    click LR "https://github.com/karimelkomy/python-test-automation-framework/blob/master/utilities/locators_read.py"
    click RJ "https://github.com/karimelkomy/python-test-automation-framework/blob/master/utilities/read_json.py"
    click RE "https://github.com/karimelkomy/python-test-automation-framework/blob/master/utilities/read_excel.py"
    click TS "https://github.com/karimelkomy/python-test-automation-framework/blob/master/utilities/teststatus.py"
    click UT "https://github.com/karimelkomy/python-test-automation-framework/blob/master/utilities/util.py"
    click TRCFG "https://github.com/karimelkomy/python-test-automation-framework/blob/master/testrail.cfg"
    click REQ "https://github.com/karimelkomy/python-test-automation-framework/blob/master/requirements.txt"

    %% Styles
    classDef runner fill:#d1c4e9,stroke:#333,stroke-width:1px;
    classDef core fill:#e0f7fa,stroke:#333,stroke-width:1px;
    classDef data fill:#fff9c4,stroke:#333,stroke-width:1px;
    classDef utils fill:#f0f4c3,stroke:#333,stroke-width:1px;
    classDef integration fill:#c8e6c9,stroke:#333,stroke-width:1px;
    classDef external fill:#ffcdd2,stroke:#333,stroke-width:1px;
```
