# jihadrusnanda/learn-playwright architecture

> Architecture diagram of the GitHub repository jihadrusnanda/learn-playwright, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jihadrusnanda/learn-playwright
- Repository: https://github.com/jihadrusnanda/learn-playwright

## Overview

##### Main Components

- Test Automation Engine:
- Playwright is the primary tool for browser automation.
- Cucumber is used to define BDD-style feature files (located under src/features) and drive test scenarios based on step definitions (under src/step-definitions).
- Jest covers the unit testing aspects (with tests and reports generated in jest-results/).

- Page Object Model:
- Located under src/pages (with subdirectories for BasePage, LoginPage, etc.), these components abstract actual page interactions.
- These objects interface with Playwright to encapsulate selectors and page behavior.

- Configuration & Support:
- Configuration files (e.g., src/config/Config.ts) and support utilities (src/support/world.ts) provide common and global settings that dictate test behavior.
- Shared selectors defined under src/selectors serve as an abstraction layer for element locations.

- CI/CD & Test Reporting Infrastructure:
- GitHub Actions workflows and reusable actions (under .github/workflows and .github/actions) drive continuous integration testing.
- Scripts (in the scripts folder) provide local debugging and act integration.
- Artifact storage directories for reports (e.g., screenshots, videos, coverage reports, and artifacts).

##### Relationships and Interactions

- BDD Flow:
- Feature Files (src/features) → Step Definitions (src/step-definitions): Feature files written in Gherkin drive the corresponding steps which in turn invoke methods on Page Objects.
- Page Objects (src/pages) ←→ Playwright: They are the interface for handling browser actions, which are logged and verified through Playwright commands.
- Configuration (src/config) and Support (src/support): Provide global test configurations and world parameters that are accessed by step definitions and page objects.

- CI/CD Integration:
- GitHub Actions triggers test execution (either via unit tests or BDD tests) using Node.js and acts as the orchestration engine.
- Dependency and artifact management steps clearly indicating caching, parallel execution, and artifact uploading.
- Local testing via act (using provided scripts like run-github-workflow.sh and debug scripts under the scripts directory).

##### Architectural Patterns and Design Principles

- Modular Organization:
- The separation of concerns is evident where features, step definitions, page objects, and configuration are distinct modules.
- Each module has its dedicated folder which helps in isolating testing code from configuration and utility logic.

- Abstraction:
- The Page Object Model abstracts UI interactions.
- Selectors and configuration files promote reuse and consistent access to environment-specific settings.

- CI/CD and Test Automation Optimizations:
- Use of dependency caching, composite actions, and optimized artifact handling make the test framework robust and efficient.

##### Relevant Technologies, Frameworks, and Dependencies

- TypeScript is used throughout to ensure type safety.
- Playwright for browser automation, with features like video recording and screenshot capture.
- Cucumber for BDD tests, enabling feature-driven development.
- Jest for running unit tests.
- GitHub Actions and act for CI/CD management.
- Additional utilities include dotenv for environment variables and cucumber-html-reporter for generating reports.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Test Automation Engine
    subgraph "Test Automation Engine"
        FF["Feature Files (BDD)"]:::testFramework
        SD["Step Definitions"]:::testFramework
        JT["Jest Unit Tests"]:::testFramework
        PW["Playwright Engine"]:::testFramework
    end

    %% Page Object Model
    subgraph "Page Object Model"
        POM["Page Objects"]:::pageobject
        BP["Base Page Object"]:::pageobject
        LP["Login Page Object"]:::pageobject
    end

    %% Configuration & Support
    subgraph "Configuration & Support"
        CFG["Global Configuration"]:::config
        SUP["Support Utilities"]:::config
        SEL["Shared Selectors"]:::config
    end

    %% CI/CD & Test Reporting Infrastructure
    subgraph "CI/CD & Test Reporting"
        subgraph "GitHub Actions Workflows"
            FT["Feature Tests Workflow"]:::cicd
            PT["Playwright Tests Workflow"]:::cicd
            UT["Unit Tests Workflow"]:::cicd
            LT["Local Test Workflow"]:::cicd
        end
        RA["Dependency Setup Action"]:::cicd
        subgraph "Local Testing & Debug Scripts"
            DS1["Debug Script (debug-ci.sh)"]:::cicd
            DS2["Debug Script (debug-with-act.sh)"]:::cicd
        end
        WR["Workflow Runner Script"]:::cicd
    end

    %% Relationships
    %% BDD Flow & Test Execution
    FF -->|"triggers"| SD
    SD -->|"invokes"| POM
    POM -->|"calls"| PW

    %% Configuration and Support influence
    CFG -.->|"config"| SD
    SUP -.->|"support"| SD
    SEL -.->|"selectors"| POM

    %% Jest tests connection (unit testing in parallel)
    SD ---|"supports"| JT

    %% CI/CD triggering test automation
    FT -->|"triggers"| FF
    UT -->|"triggers"| JT
    LT -->|"triggers"| SD
    DS1 -->|"executes"| JT
    DS2 -->|"executes"| JT
    RA -->|"prepares"| FT
    WR -->|"runs"| FT

    %% Interconnection between CI/CD and Test Execution
    PW -->|"reports artifacts"| UT

    %% Page Object internal connections
    POM --- BP
    POM --- LP

    %% Click Events for Test Automation Engine
    click FF "https://github.com/jihadrusnanda/learn-playwright/tree/main/src/features"
    click SD "https://github.com/jihadrusnanda/learn-playwright/tree/main/src/step-definitions"
    click JT "https://github.com/jihadrusnanda/learn-playwright/blob/main/src/utils/example.test.ts"
    
    %% Click Events for Page Object Model
    click POM "https://github.com/jihadrusnanda/learn-playwright/tree/main/src/pages"
    click BP "https://github.com/jihadrusnanda/learn-playwright/blob/main/src/pages/base/BasePage.ts"
    click LP "https://github.com/jihadrusnanda/learn-playwright/blob/main/src/pages/login/LoginPage.ts"
    
    %% Click Events for Configuration & Support
    click CFG "https://github.com/jihadrusnanda/learn-playwright/blob/main/src/config/Config.ts"
    click SUP "https://github.com/jihadrusnanda/learn-playwright/blob/main/src/support/world.ts"
    click SEL "https://github.com/jihadrusnanda/learn-playwright/tree/main/src/selectors"
    
    %% Click Events for CI/CD & Test Reporting Infrastructure
    click FT "https://github.com/jihadrusnanda/learn-playwright/blob/main/.github/workflows/feature-tests.yml"
    click PT "https://github.com/jihadrusnanda/learn-playwright/blob/main/.github/workflows/playwright.yml"
    click UT "https://github.com/jihadrusnanda/learn-playwright/blob/main/.github/workflows/unit-tests.yml"
    click LT "https://github.com/jihadrusnanda/learn-playwright/blob/main/.github/workflows/local-test.yml"
    click RA "https://github.com/jihadrusnanda/learn-playwright/blob/main/.github/actions/setup-dependencies/action.yml"
    click DS1 "https://github.com/jihadrusnanda/learn-playwright/blob/main/scripts/debug-ci.sh"
    click DS2 "https://github.com/jihadrusnanda/learn-playwright/blob/main/scripts/debug-with-act.sh"
    click WR "https://github.com/jihadrusnanda/learn-playwright/blob/main/run-github-workflow.sh"

    %% Styles
    classDef testFramework fill:#FFF3CD,stroke:#FFCC00,stroke-width:2px;
    classDef pageobject fill:#F8D7DA,stroke:#E4606D,stroke-width:2px;
    classDef config fill:#D1E7DD,stroke:#0F5132,stroke-width:2px;
    classDef cicd fill:#D1ECF1,stroke:#0C5460,stroke-width:2px;
```
