# amromoussa2211/willma-trainer architecture

> Architecture diagram of the GitHub repository amromoussa2211/willma-trainer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amromoussa2211/willma-trainer
- Repository: https://github.com/amromoussa2211/willma-trainer

## Overview

##### Project type and purpose
- This is a Test Automation Framework for Android applications.
- Built on Node.js using WebdriverIO (test runner) and Appium (mobile automation).
- Supports both local and CI/CD execution and produces Allure test reports.

##### File structure
- Root
- `.env` – environment variables for deviceName, platformVersion, etc.
- `package.json` – npm scripts (start:appium, test:local, test:ci, generate-report, open-report).
- `wdio.conf.js`, `wdio.local.conf.js`, `wdio.ci.conf.js` – WebdriverIO configurations for default, local, and CI runs.
- `.github/workflows` – GitHub Actions CI pipelines (`ci.yml`, `main.yml`, `runE2E.yml`).
- `apps/android` – directory for the APK(s) under test.
- Test directory
- `test/specs` – E2E test scenarios organized by feature (signup, forms, analytics, API checks).
- `test/pageobjects` – page-object pattern abstractions (`login.page.js`, `secure.page.js`, `page.js`).
- CI/Reporting
- Allure results (generated under `allure-results`) and final reports (`allure-report`).

##### Key architectural elements from the README
- Java/Android SDK + Appium server (mobile automation backend).
- WebdriverIO test runner invoking Appium sessions.
- Page-object model for test maintainability.
- Environment-specific config (local vs CI).
- Allure for test reporting.
- GitHub Actions pipelines orchestrating CI tests and report publishing.

##### Main components
- Developer/CI Host
- Node.js runtime
- Java JDK + Android SDK
- Appium Server
- Receives WebdriverIO commands over WebDriver protocol.
- WebdriverIO Test Runner
- Loads `wdio.*.conf.js` based on environment.
- Executes test specs (`test/specs`) using page-object abstractions.
- Android Device/Emulator
- Installs and runs the target APK from `apps/android`.
- Allure Reporting
- Aggregates test results (`allure-results`).
- Generates and serves HTML reports (`allure-report`).
- GitHub Actions (CI)
- Checkout → Install dependencies → Start Appium server → Run `npm run test:ci` → Publish Allure results/artifacts.

##### Relationships and interactions
- The Test Runner sends commands to the Appium Server.
- Appium Server drives the Android Device/Emulator.
- Test specs reference page-objects to locate and interact with UI elements.
- Test results funnel into Allure, which produces reports.
- CI pipelines automate this sequence on pull requests or merges.

##### Architectural patterns and design principles
- Page-Object Model: separates element locators/actions (`test/pageobjects`) from test logic (`test/specs`).
- Environment configuration abstraction: separate `wdio.local.conf.js` and `wdio.ci.conf.js`.
- Modular scripts in `package.json` for starting Appium, running tests, and generating reports.
- CI integration via GitHub Actions workflows.

##### Detail
- Both high-level flow (CI vs local) and low-level modules (page-objects, specs).
- How environment variables and config files influence each component.
- Don’t omit the APK under test or the Allure report directory.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Host Environment
    subgraph "Host Environment"
        direction TB
        NodeJS["Node.js Runtime"]:::blue
        JavaSDK["Java JDK + Android SDK"]:::blue
        Env["Environment Configuration (.env)"]:::blue
        PackageJSON["NPM Scripts & Project Metadata\n(package.json)"]:::blue
    end

    %% Local Execution Lane
    subgraph "Local Execution" 
        direction TB
        LocalRunner["WebdriverIO Test Runner (Local)\nwdio.local.conf.js"]:::orange
    end

    %% CI Execution Lane
    subgraph "CI Execution (GitHub Actions)" 
        direction TB
        CIAction["GitHub Actions Workflows"]:::gray
        CIRunner["WebdriverIO Test Runner (CI)\nwdio.ci.conf.js"]:::orange
    end

    %% Shared Components
    subgraph "Test Framework Components"
        direction TB
        WDIODefault["Default WDIO Config\nwdio.conf.js"]:::orange
        Appium["Appium Server"]:::orange
        PageObjects["Page-Object Model\n(test/pageobjects)"]:::green
        Specs["E2E Test Scenarios\n(test/specs)"]:::green
    end

    subgraph "Device Under Test"
        direction TB
        APK["Android Application Under Test\n(apps/android)"]:::green
        Device["Android Device/Emulator"]:::green
    end

    subgraph "Reporting"
        direction TB
        AllureResults["Allure Results\n(allure-results)"]:::purple
        AllureReport["Allure Report\n(allure-report)"]:::purple
    end

    %% Connections: Host to Runners
    NodeJS -->|"runs"| LocalRunner
    JavaSDK -->|"dependencies"| LocalRunner
    Env -->|"loads vars"| LocalRunner
    PackageJSON -->|"npm script test:local"| LocalRunner

    NodeJS -->|"runs"| CIRunner
    JavaSDK -->|"dependencies"| CIRunner
    Env -->|"loads vars"| CIRunner
    PackageJSON -->|"npm script test:ci"| CIRunner

    CIAction -->|"triggers"| CIRunner

    %% Default config injected
    LocalRunner -->|"extends"| WDIODefault
    CIRunner -->|"extends"| WDIODefault

    %% Runner to Appium
    LocalRunner -->|"WebDriver Commands"| Appium
    CIRunner -->|"WebDriver Commands"| Appium

    %% Appium to Device
    Appium -->|"drives"| Device
    Device -->|"installs APK"| APK
    APK -->|"target under test"| Device

    %% Runner uses PageObjects and Specs
    LocalRunner -->|"loads specs"| Specs
    CIRunner -->|"loads specs"| Specs
    Specs -->|"uses"| PageObjects

    %% Reporting flow
    LocalRunner -->|"writes results"| AllureResults
    CIRunner -->|"writes results"| AllureResults
    AllureResults -->|"generates"| AllureReport

    CIAction -->|"publishes"| AllureReport

    %% Click events
    click Env "https://github.com/amromoussa2211/willma-trainer/blob/main/.env"
    click PackageJSON "https://github.com/amromoussa2211/willma-trainer/blob/main/package.json"
    click WDIODefault "https://github.com/amromoussa2211/willma-trainer/blob/main/wdio.conf.js"
    click LocalRunner "https://github.com/amromoussa2211/willma-trainer/blob/main/wdio.local.conf.js"
    click CIRunner "https://github.com/amromoussa2211/willma-trainer/blob/main/wdio.ci.conf.js"
    click CIAction "https://github.com/amromoussa2211/willma-trainer/blob/main/.github/workflows/ci.yml"
    click CIAction "https://github.com/amromoussa2211/willma-trainer/blob/main/.github/workflows/main.yml"
    click CIAction "https://github.com/amromoussa2211/willma-trainer/blob/main/.github/workflows/runE2E.yml"
    click APK "https://github.com/amromoussa2211/willma-trainer/tree/main/apps/android"
    click PageObjects "https://github.com/amromoussa2211/willma-trainer/tree/main/test/pageobjects"
    click Specs "https://github.com/amromoussa2211/willma-trainer/tree/main/test/specs"
    click PageObjects "https://github.com/amromoussa2211/willma-trainer/blob/main/test/pageobjects/login.page.js"
    click PageObjects "https://github.com/amromoussa2211/willma-trainer/blob/main/test/pageobjects/secure.page.js"
    click PageObjects "https://github.com/amromoussa2211/willma-trainer/blob/main/test/pageobjects/page.js"

    %% Styles
    classDef blue fill:#D0E8FF,stroke:#1E90FF,color:#000
    classDef orange fill:#FFE4B5,stroke:#FF8C00,color:#000
    classDef green fill:#D6F5D6,stroke:#32CD32,color:#000
    classDef purple fill:#E5CCFF,stroke:#9370DB,color:#000
    classDef gray fill:#F2F2F2,stroke:#A9A9A9,color:#000
```
