# rgenes28/ecom-automation architecture

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

- Interactive diagram: https://gitdiagram.com/rgenes28/ecom-automation
- Repository: https://github.com/rgenes28/ecom-automation

## Overview

##### Project Type and Purpose
- This is a QA automation framework built with Playwright and TypeScript.
- Its goal is to automate end-to-end (E2E) tests against an e-commerce application using the Page Object Model (POM), custom API clients, and utility modules.
- Tests are orchestrated locally and in CI via GitHub Actions.

##### File Structure Analysis
- Top-level configuration
- .env, .dev.env, .prod.env, env.config.ts: environment variables and runtime config
- playwright.config.ts: Playwright Test runner settings
- .github/workflows/playwright-tests.yml: CI pipeline definition
- Core framework layers
- pages/: POM classes (HomePage, LoginPage, RegisterPage, CheckoutPage, etc.)
- api-clients/: wrappers for REST calls (order.api-client.ts, user.api-client.ts)
- utils/: shared helpers (apiEcomus.ts, data generation, logging)
- data/: test data definitions (testdata.ts)
- Test suites
- tests/: canonical E2E test specs (login, home, register, checkout, e2e)
- tests-examples/: demo or scratch specs (demo-todo-app.spec.ts)
- Artifacts
- screenshots/: captures from failed or validated tests
- Dependency files
- package.json / package-lock.json

##### Architectural Patterns
- Page Object Model (separation of test logic and UI interaction)
- Layered design
1. Test Runner (Playwright Test)
2. Test Specs (tests/)
3. Domain Models (pages/, api-clients/, utils/)
- Environment-driven configuration for different targets (dev, prod, CI)

##### Main Components & Interactions
a. Playwright Test Runner
- Reads playwright.config.ts and env.config.ts
- Spawns browser contexts and test workers
- Orchestrates lifecycle hooks (beforeAll, afterEach, etc.)
b. Test Specs (tests/, tests-examples/)
- Scenarios using POM and API clients
- Import page objects, utils, test data
c. Page Objects (pages/)
- Expose methods to interact with UI (click, type, expect)
- Encapsulate locators and selectors
d. API Clients (api-clients/)
- Provide direct REST access for setup/teardown or bypass UI
e. Utilities (utils/, data/)
- Data providers, random-data generation, custom assertions
f. Configuration Layer
- .env files, env.config.ts control baseURLs, credentials
g. CI/CD (GitHub Actions)
- Triggers on push or PR
- Installs dependencies, runs Playwright tests, uploads artifacts (screenshots, traces)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Left: Configuration & CI/CD
    subgraph "Configuration & CI/CD"
        DevEnv[".dev.env"]:::config
        Env[".env"]:::config
        ProdEnv[".prod.env"]:::config
        EnvConfig["env.config.ts"]:::config
        CI["GitHub Actions Pipeline"]:::ci
    end

    click DevEnv "https://github.com/rgenes28/ecom-automation/blob/main/.dev.env"
    click Env "https://github.com/rgenes28/ecom-automation/blob/main/.env"
    click ProdEnv "https://github.com/rgenes28/ecom-automation/blob/main/.prod.env"
    click EnvConfig "https://github.com/rgenes28/ecom-automation/blob/main/env.config.ts"
    click CI "https://github.com/rgenes28/ecom-automation/blob/main/.github/workflows/playwright-tests.yml"

    %% Center: Test Runner
    Runner["Playwright Test Runner"]:::playwright
    click Runner "https://github.com/rgenes28/ecom-automation/blob/main/playwright.config.ts"

    %% Surrounding modules
    subgraph "Test Specs" 
        HomeSpec["home.page.spec.ts"]:::modules
        LoginSpec["login.spec.ts"]:::modules
        RegisterSpec["register.page.spec.ts"]:::modules
        CheckoutSpec["checkout.spec.ts"]:::modules
        E2ESpec["e2e.spec.ts"]:::modules
    end

    click HomeSpec "https://github.com/rgenes28/ecom-automation/blob/main/tests/home.page.spec.ts"
    click LoginSpec "https://github.com/rgenes28/ecom-automation/blob/main/tests/login.spec.ts"
    click RegisterSpec "https://github.com/rgenes28/ecom-automation/blob/main/tests/register.spec.ts"
    click CheckoutSpec "https://github.com/rgenes28/ecom-automation/blob/main/tests/checkout.spec.ts"
    click E2ESpec "https://github.com/rgenes28/ecom-automation/blob/main/tests/e2e.spec.ts"

    subgraph "Demo Specs"
        DemoSpec["demo-todo-app.spec.ts"]:::modules
    end
    click DemoSpec "https://github.com/rgenes28/ecom-automation/blob/main/tests-examples/demo-todo-app.spec.ts"

    subgraph "Page Objects (POM)"
        HomePage["home.page.ts"]:::modules
        LoginPage["login.page.ts"]:::modules
        RegisterPage["register.page.ts"]:::modules
        CheckoutPage["checkout.page.ts"]:::modules
        CartComponent["cart.component.ts"]:::modules
        MyAccountPage["myaccount.page.ts"]:::modules
        ProductPage["product.page.ts"]:::modules
    end

    click HomePage "https://github.com/rgenes28/ecom-automation/blob/main/pages/home.page.ts"
    click LoginPage "https://github.com/rgenes28/ecom-automation/blob/main/pages/login.page.ts"
    click RegisterPage "https://github.com/rgenes28/ecom-automation/blob/main/pages/register.page.ts"
    click CheckoutPage "https://github.com/rgenes28/ecom-automation/blob/main/pages/checkout.page.ts"
    click CartComponent "https://github.com/rgenes28/ecom-automation/blob/main/pages/cart.component.ts"
    click MyAccountPage "https://github.com/rgenes28/ecom-automation/blob/main/pages/myaccount.page.ts"
    click ProductPage "https://github.com/rgenes28/ecom-automation/blob/main/pages/product.page.ts"

    subgraph "API Clients"
        UserApi["user.api-client.ts"]:::modules
        OrderApi["order.api-client.ts"]:::modules
    end

    click UserApi "https://github.com/rgenes28/ecom-automation/blob/main/api-clients/user.api-client.ts"
    click OrderApi "https://github.com/rgenes28/ecom-automation/blob/main/api-clients/order.api-client.ts"

    subgraph "Utilities & Data"
        ApiEcomus["apiEcomus.ts"]:::modules
        TestData["testdata.ts"]:::modules
    end

    click ApiEcomus "https://github.com/rgenes28/ecom-automation/blob/main/utils/apiEcomus.ts"
    click TestData "https://github.com/rgenes28/ecom-automation/blob/main/data/testdata.ts"

    %% Right: External Systems under test
    subgraph "External Systems"
        WebUI("Web Application UI"):::external
        BackendAPI("Backend REST API"):::external
        Database["Database"]:::external
    end

    %% Bottom: Artifacts
    Artifacts["screenshots/"]:::artifacts

    %% Relationships
    DevEnv -->|"provides env"| Runner
    Env -->|"provides env"| Runner
    ProdEnv -->|"provides env"| Runner
    EnvConfig -->|"loads config"| Runner
    CI -->|"triggers"| Runner

    Runner -->|"executes"| HomeSpec
    Runner -->|"executes"| LoginSpec
    Runner -->|"executes"| RegisterSpec
    Runner -->|"executes"| CheckoutSpec
    Runner -->|"executes"| E2ESpec
    Runner -->|"executes"| DemoSpec

    HomeSpec -->|"uses"| HomePage
    HomeSpec -->|"uses"| ApiEcomus
    LoginSpec -->|"uses"| LoginPage
    RegisterSpec -->|"uses"| RegisterPage
    CheckoutSpec -->|"uses"| CheckoutPage
    CheckoutSpec -->|"uses"| CartComponent
    E2ESpec -->|"uses"| ProductPage
    DemoSpec -->|"uses"| MyAccountPage

    HomeSpec -->|"calls"| UserApi
    CheckoutSpec -->|"calls"| OrderApi

    ApiEcomus -->|"reads"| TestData

    HomePage -->|"interacts"| WebUI
    LoginPage -->|"interacts"| WebUI
    RegisterPage -->|"interacts"| WebUI
    CheckoutPage -->|"interacts"| WebUI
    CartComponent -->|"interacts"| WebUI
    MyAccountPage -->|"interacts"| WebUI
    ProductPage -->|"interacts"| WebUI

    UserApi -->|"calls REST"| BackendAPI
    OrderApi -->|"calls REST"| BackendAPI
    BackendAPI -->|"stores/retrieves"| Database

    Runner -->|"writes"| Artifacts
    CI -->|"collects"| Artifacts

    %% Styles
    classDef config fill:#cccccc,stroke:#333,stroke-width:1px
    classDef ci fill:#dddddd,stroke:#444,stroke-width:1px,stroke-dasharray: 5 5
    classDef playwright fill:#afe1ff,stroke:#0288d1,stroke-width:2px
    classDef modules fill:#d5f5d5,stroke:#27ae60,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#e65100,stroke-width:2px,stroke-dasharray:2 2
    classDef artifacts fill:#f2f2f2,stroke:#999,stroke-width:1px,stroke-dasharray:2 2
```
