# nirtal85/selenium-python-example architecture

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

- Interactive diagram: https://gitdiagram.com/nirtal85/selenium-python-example
- Repository: https://github.com/nirtal85/selenium-python-example

## Overview

##### Project type and purpose
- This is a test-automation framework (not an end-user app).
- Purpose: drive browser-based UI tests (login, project management, templates, etc.), parse data, validate visuals, send emails, report results.

##### File structure
- Top-level:
- src/pages → Page-Object classes (POM).
- src/utilities → Helpers (excel parsing, VRT, mailinator, listener).
- src/enums → Shared enums (test status).
- resources → Static test data (Excel, JSON).
- tests → Pytest test modules and fixtures.
- pyproject.toml & .env → Config/dependencies.
- .github/workflows → CI/CD pipelines (devRun, nightly).

##### README insights
- Tech stack includes Selenium, Pytest (+plugins), Allure, VRT, Mailinator, MySQL connector, tenacity, etc.
- CI via GitHub Actions triggers tests and publishes Allure reports.

##### Main components & relationships
a. Test Runner Layer
- Pytest CLI (with plugins) reads config, discovers tests under tests/.
- .env loader (python-dotenv) provides secrets/config.
b. Test Scripts
- tests/*.py import Page Objects and utilities.
- conftest.py defines fixtures (WebDriver instantiation, base URLs).
c. Page-Object Layer
- src/pages/**/*.py encapsulate UI interactions (login_page, projects_page, top_menu_bar, etc.).
- BasePage provides common methods (click, find, wait).
d. Utilities
- excel_parser reads resources/data.xls.
- data.py loads JSON or Excel into models.
- mailinator_helper interacts with Mailinator API.
- vrt_helper interacts with Visual-Regression-Tracker service.
- web_driver_listener hooks into WebDriver events for logging/screenshots.
e. External Services
- Browser Driver (Chrome/Firefox) controlled by selenium.
- MySQL DB (via mysql-connector) for any data validations (db_test).
- Mailinator service for email‐based tests.
- Visual Regression Tracker for visual diffs.
- Allure report server (local or GitHub Pages).
f. CI/CD
- GitHub Actions workflows (devRun, nightly) execute tests, collect results, publish to Allure.

##### Architectural patterns & design principles
- Page Object Model (POM) separates test logic from page interactions.
- Layered architecture: Tests → POM → Utilities → External services.
- Dependency injection via fixtures for WebDriver, base-URL, credentials.
- Config management (.env, python-dotenv).
- Observer pattern: WebDriverListener captures events.
- Retry logic: tenacity for resilient steps.
- Soft assertions and test ordering via pytest plugins.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CI/CD Workflows"
        DEV["devRun.yml"]:::ci
        NIGHTLY["nightly.yml"]:::ci
    end
    subgraph "Test Runner Layer"
        PYTEST["Pytest CLI (with plugins)"]:::code
        CONFIG[".env"]:::config
    end
    DEV -->|"triggers tests"| PYTEST
    NIGHTLY -->|"triggers tests"| PYTEST
    PYTEST -->|"reads config"| CONFIG
    subgraph "Test Scripts"
        TESTS_DIR["tests/"]:::code
        CONFT["conftest.py"]:::code
        BASE_TEST["base_test.py"]:::code
        DB_TEST["db_test.py"]:::code
        DEP_CLASS_TEST["dependency_class_test.py"]:::code
        DEP_TEST["dependency_test.py"]:::code
        EMAIL_TEST["email_test.py"]:::code
        FORGOT_TEST["forgot_password_test.py"]:::code
        LOGIN_TEST["login_test.py"]:::code
        VISUAL_TEST["visual_test.py"]:::code
        WORKSPACES_TEST["workspaces_test.py"]:::code
    end
    PYTEST -->|"discovers tests"| TESTS_DIR
    TESTS_DIR --> CONFT
    TESTS_DIR --> BASE_TEST
    TESTS_DIR --> DB_TEST
    TESTS_DIR --> DEP_CLASS_TEST
    TESTS_DIR --> DEP_TEST
    TESTS_DIR --> EMAIL_TEST
    TESTS_DIR --> FORGOT_TEST
    TESTS_DIR --> LOGIN_TEST
    TESTS_DIR --> VISUAL_TEST
    TESTS_DIR --> WORKSPACES_TEST
    CONFT -->|"provides fixtures"| TESTS_DIR

    subgraph "Page-Object Layer"
        POM_DIR["src/pages/"]:::code
        BASE_PAGE["base_page.py"]:::code
        ABOUT_PAGE["about_page.py"]:::code
        FORGOT_PAGE["forgot_password_page.py"]:::code
        LOGIN_PAGE["login_page.py"]:::code
        PROJECT_EDIT["project_edit_page.py"]:::code
        PROJECT_TYPE["project_type_page.py"]:::code
        PROJECTS_PAGE["projects_page.py"]:::code
        TEMPLATES_PAGE["templates_page.py"]:::code
        TOP_MENU["top_menu_bar.py"]:::code
        TOP_NAV["top_navigate_bar.py"]:::code
    end
    TESTS_DIR -->|"uses POM classes"| POM_DIR
    POM_DIR --> BASE_PAGE
    POM_DIR --> ABOUT_PAGE
    POM_DIR --> FORGOT_PAGE
    POM_DIR --> LOGIN_PAGE
    POM_DIR --> PROJECT_EDIT
    POM_DIR --> PROJECT_TYPE
    POM_DIR --> PROJECTS_PAGE
    POM_DIR --> TEMPLATES_PAGE
    POM_DIR --> TOP_MENU
    POM_DIR --> TOP_NAV

    subgraph "Utilities"
        UTIL_DIR["src/utilities/"]:::code
        CONST["constants.py"]:::code
        DATA_UTIL["data.py"]:::code
        EXCEL["excel_parser.py"]:::code
        MAIL_HELP["mailinator_helper.py"]:::code
        VRT_HELP["vrt_helper.py"]:::code
        LISTENER["web_driver_listener.py"]:::code
    end
    POM_DIR -->|"calls utilities"| UTIL_DIR
    UTIL_DIR --> CONST
    UTIL_DIR --> DATA_UTIL
    UTIL_DIR --> EXCEL
    UTIL_DIR --> MAIL_HELP
    UTIL_DIR --> VRT_HELP
    UTIL_DIR --> LISTENER

    subgraph "Shared Enums"
        ENUM_DIR["src/enums/status.py"]:::code
    end
    TESTS_DIR --> ENUM_DIR
    POM_DIR --> ENUM_DIR
    UTIL_DIR --> ENUM_DIR

    subgraph "Static Test Data"
        DATA_XLS["data.xls"]:::data
        JSON_DATA["tests_data.json"]:::data
    end
    EXCEL --> DATA_XLS
    DATA_UTIL --> JSON_DATA

    subgraph "External Services"
        BROWSER["Browser Driver (Chrome/Firefox)"]:::external
        DB["MySQL DB"]:::external
        MAIL_SERVICE["Mailinator API"]:::external
        VRT_SERVICE["Visual Regression Tracker"]:::external
        ALLURE_SERVER["Allure Report Server"]:::external
    end
    POM_DIR -->|"Selenium commands"| BROWSER
    UTIL_DIR --> MAIL_SERVICE
    UTIL_DIR --> VRT_SERVICE
    DB_TEST --> DB
    LISTENER --> ALLURE_SERVER

    subgraph "Reporting"
        ALLURE_RESULTS["Allure Results Directory"]:::data
    end
    PYTEST -->|"outputs reports"| ALLURE_RESULTS
    ALLURE_RESULTS --> ALLURE_SERVER

    classDef code fill:#a8d0e6,stroke:#303841,color:#000;
    classDef data fill:#c3f584,stroke:#303841,color:#000,stroke-width:1px;
    classDef external fill:#ffb482,stroke:#303841,color:#000;
    classDef config fill:#d3d3d3,stroke:#303841,color:#000;
    classDef ci fill:#b28ddb,stroke:#303841,color:#000;

    click TESTS_DIR "https://github.com/nirtal85/selenium-python-example/tree/main/tests/"
    click CONFT "https://github.com/nirtal85/selenium-python-example/blob/main/tests/conftest.py"
    click BASE_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/base_test.py"
    click DB_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/db_test.py"
    click DEP_CLASS_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/dependency_class_test.py"
    click DEP_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/dependency_test.py"
    click EMAIL_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/email_test.py"
    click FORGOT_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/forgot_password_test.py"
    click LOGIN_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/login_test.py"
    click VISUAL_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/visual_test.py"
    click WORKSPACES_TEST "https://github.com/nirtal85/selenium-python-example/blob/main/tests/workspaces_test.py"

    click POM_DIR "https://github.com/nirtal85/selenium-python-example/tree/main/src/pages/"
    click BASE_PAGE "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/base_page.py"
    click ABOUT_PAGE "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/about_page.py"
    click FORGOT_PAGE "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/forgot_password_page.py"
    click LOGIN_PAGE "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/login_page.py"
    click PROJECT_EDIT "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/project_edit_page.py"
    click PROJECT_TYPE "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/project_type_page.py"
    click PROJECTS_PAGE "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/projects_page.py"
    click TEMPLATES_PAGE "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/templates_page.py"
    click TOP_MENU "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/top_bars/top_menu_bar.py"
    click TOP_NAV "https://github.com/nirtal85/selenium-python-example/blob/main/src/pages/top_bars/top_navigate_bar.py"

    click ENUM_DIR "https://github.com/nirtal85/selenium-python-example/blob/main/src/enums/status.py"

    click UTIL_DIR "https://github.com/nirtal85/selenium-python-example/tree/main/src/utilities/"
    click CONST "https://github.com/nirtal85/selenium-python-example/blob/main/src/utilities/constants.py"
    click DATA_UTIL "https://github.com/nirtal85/selenium-python-example/blob/main/src/utilities/data.py"
    click EXCEL "https://github.com/nirtal85/selenium-python-example/blob/main/src/utilities/excel_parser.py"
    click MAIL_HELP "https://github.com/nirtal85/selenium-python-example/blob/main/src/utilities/mailinator_helper.py"
    click VRT_HELP "https://github.com/nirtal85/selenium-python-example/blob/main/src/utilities/vrt_helper.py"
    click LISTENER "https://github.com/nirtal85/selenium-python-example/blob/main/src/utilities/web_driver_listener.py"

    click DATA_XLS "https://github.com/nirtal85/selenium-python-example/blob/main/resources/data.xls"
    click JSON_DATA "https://github.com/nirtal85/selenium-python-example/blob/main/resources/tests_data.json"

    click DEV "https://github.com/nirtal85/selenium-python-example/blob/main/.github/workflows/devRun.yml"
    click NIGHTLY "https://github.com/nirtal85/selenium-python-example/blob/main/.github/workflows/nightly.yml"
    click CONFIG "https://github.com/nirtal85/selenium-python-example/blob/main/.env"
```
