# blessybabu-qa/todomvc_playwright architecture

> Architecture diagram of the GitHub repository blessybabu-qa/todomvc_playwright, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blessybabu-qa/todomvc_playwright
- Repository: https://github.com/blessybabu-qa/todomvc_playwright

## Overview

##### Project type and purpose
- This is an end-to-end (E2E) test automation framework/project built with Playwright. It demonstrates advanced Page Object Model (POM) patterns and resilient semantic locators for testing the external TodoMVC web application.
- Purpose: exercise/validate UI behavior (creation, filtering, completion, clearing) of the TodoMVC app using maintainable, data-driven Playwright tests; run locally and in CI.

##### Key artifacts from the file tree / README
- pages/todoPage.js — the Page Object implementing semantic locators (getByTestId, getByRole) and UI operations.
- tests/todomvc.spec.js — test suite(s) describing scenarios (creation, filtering, management, validation) that call into the Page Object.
- playwright.config.js — Playwright configuration (browsers, baseURL, timeouts, test options, reporters).
- .github/workflows/TodoMVC_Playwright.yml — CI pipeline that runs tests in GitHub Actions.
- package.json / package-lock.json — Node + npm dependency & script surface (test, install).
- README.md — describes architecture, patterns (POM, resilient locators), tech stack, included scenarios.

##### Main components
- Test Suites / Test Runner
- Playwright Test runner + test files (tests/todomvc.spec.js)
- Page Object Layer
- pages/todoPage.js (semantic locators and high-level UI actions)
- Playwright Engine / API
- Playwright library, fixtures, auto-awaiting expect assertions
- Execution Environment / Browsers
- Chromium, Firefox, WebKit (as configured) — actual browser instances or headed/headless contexts
- System Under Test (SUT)
- TodoMVC web application (external target website; baseURL configured in playwright.config.js)
- Test Infrastructure
- Node.js / npm runtime, dependencies (package.json)
- CI/CD (GitHub Actions workflow)
- Artifacts & Reports (Playwright HTML report, screenshots, traces)
- Test Data & Utilities
- Data-driven inputs (bulk todo creation), helper functions (could live in pages or support files)
- Configuration
- playwright.config.js (browsers, baseURL, reporters, retries)
- Optional: Local developer workstation vs CI agents

##### Important architectural patterns & design principles to call out
- Page Object Model (POM): single responsibility for page objects (locators + actions), tests remain declarative. Represent POM as a separate layer between tests and Playwright API.
- Semantic / resilient locators: emphasize getByTestId / getByRole use (stability over brittle selectors). Annotate page object node with "semantic locators".
- Data-driven tests: tests accept arrays/batches for bulk todo creation; show test data feeding into tests.
- Auto-awaiting assertions: Playwright expect is auto-awaiting — mention this as part of validation pattern.
- Separation of concerns: config (playwright.config.js) decouples environment/browsers from test code.
- CI integration for repeatable runs and cross-browser matrix.

- tests/todomvc.spec.js -> "Test Suites / Scenarios" node
- pages/todoPage.js -> "Page Objects" node (annotate 'semantic locators: getByTestId, getByRole')
- playwright.config.js -> "Configuration" node (baseURL, browsers, reporters)
- .github/workflows/TodoMVC_Playwright.yml -> "CI/CD" node
- package.json -> "npm scripts & deps" node

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top triggers
    subgraph "Triggers & Actors" 
        direction TB
        Dev["Developer (local)"]:::purple
        CI["GitHub Actions CI"]:::purple
        Dev -->|runs:npm_run_test| LocalScript["npm run test / npx playwright test"]:::gray
        CI -->|triggers:workflow| Workflow[".github/workflows/TodoMVC_Playwright.yml"]:::purple
        click Workflow "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/.github/workflows/TodoMVC_Playwright.yml"
    end

    %% Runtime & package layer
    subgraph "Runtime & Package" 
        direction TB
        Node["Node.js / npm (runtime & deps)"]:::green
        PackageJSON["package.json"]:::gray
        Lockfile["package-lock.json"]:::gray
        Node -->|runtime_executes| TestRunner["Playwright Test Runner"]:::blue
        click PackageJSON "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/package.json"
        click Lockfile "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/package-lock.json"
    end

    Workflow -->|runs:npm_install_and_test| Node
    LocalScript -->|executes| Node

    %% Config
    subgraph "Configuration" 
        direction TB
        Config["Playwright Configuration"]:::config
        ConfigLabel["playwright.config.js\n(browsers, baseURL, reporters, timeouts)"]:::config
        Config -->|influences| TestRunner
        click ConfigLabel "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/playwright.config.js"
    end

    %% Tests layer
    subgraph "Tests & Suites" 
        direction TB
        Tests["Test Suites / Scenarios\n(tests/todomvc.spec.js)"]:::blue
        Tests -->|calls/uses| PageObjects["Page Objects Layer\n(pages/todoPage.js)\n[POM + semantic locators: getByTestId,getByRole]"]:::blue
        click Tests "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/tests/todomvc.spec.js"
        click PageObjects "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/pages/todoPage.js"
    end

    TestRunner -->|runs| Tests
    TestRunner -->|loads_config| Config

    %% Detailed Page Object inset
    subgraph "Page Object - Detailed View" 
        direction TB
        POM["todoPage.js"]:::blue
        Locators["Locators\n(getByTestId,getByRole)"]:::gray
        Actions["Actions\naddTodo(),toggleTodo(),clearCompleted(),filter()"]:::blue
        StateReaders["Read/Assert methods\ncountActive(),listTodos()"]:::blue
        Helpers["Helpers & TestData\n(data-driven inputs)"]:::gray

        POM --> Locators
        POM --> Actions
        POM --> StateReaders
        POM --> Helpers
    end

    PageObjects -->|encapsulates| POM

    %% Playwright Engine
    subgraph "Playwright Engine / API" 
        direction TB
        API["Playwright Library & Fixtures\n(auto-await expect, page, context)"]:::green
        API -->|launches/controls| Browsers["Browser Matrix\nChromium,Firefox,WebKit\n(separate contexts per test)"]:::green
        API -->|provides| Expect["auto-awaiting expects/assertions"]:::gray
    end

    PageObjects -->|uses:Playwright_API| API
    Tests -->|uses:fixtures| API
    click Config "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/playwright.config.js"

    %% Browsers to SUT
    subgraph "Browsers & SUT" 
        direction TB
        BrowsersInstance["BrowserInstances\n(headed/local or headless/CI)"]:::green
        BrowsersInstance -->|navigates/HTTP| SUT["TodoMVC Web App (External)\n(baseURL in config)"]:::orange
        SUT -->|responds| BrowsersInstance
    end

    API -->|launches/creates_contexts| BrowsersInstance

    %% Artifacts and Reports
    subgraph "Artifacts & Observability" 
        direction TB
        Reports["Playwright HTML Report\nScreenshots,Traces,Artifacts"]:::cylinder
        Tests -->|produces:artifacts| Reports
        CI -->|stores_uploads| Reports
    end

    click Reports "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/README.md" "README.md"

    %% High-level flows (numbered scenarios)
    subgraph "Scenario Flows (Example: Creation)" 
        direction TB
        S1["1) tests/todomvc.spec.js: createTodos() -> calls todoPage.addTodo(text)"]:::note
        S2["2) todoPage.addTodo -> uses getByRole/getByTestId + page.type/press"]:::note
        S3["3) Playwright -> issues browser inputs (contexts/pages)"]:::note
        S4["4) Browser -> navigates/HTTP -> TodoMVC responds/DOM updates"]:::note
        S5["5) expect assertions validate UI -> failures capture screenshots/traces"]:::note

        Tests -->|executes_scenario| S1
        S1 -->|calls| S2
        S2 -->|uses_API| S3
        S3 -->|controls| S4
        S4 -->|renders| S5
        S5 -->|produces| Reports
    end

    %% Additional relationships & CI matrix
    Workflow -->|matrix_runs_per_browser| TestRunner
    TestRunner -->|parallel_runs| BrowsersInstance

    %% Legend
    subgraph "Legend" 
        direction TB
        Lc1["Rectangles: Logical components (code)"]:::legend
        Lc2["Cylinders: Artifacts/Storage"]:::legend
        Lc3["Green: Runtime & infra"]:::legend
        Lc4["Blue: Code artifacts (tests/pages)"]:::legend
        Lc5["Orange: External SUT"]:::legend
        Lc6["Purple: CI / Developers"]:::legend
    end

    %% Styles
    classDef blue fill:#cfe8ff,stroke:#1f6feb,stroke-width:1px,color:#003366;
    classDef green fill:#e6ffea,stroke:#1f9d4a,stroke-width:1px,color:#0b6623;
    classDef orange fill:#fff0e0,stroke:#ff8c42,stroke-width:1px,color:#663300;
    classDef gray fill:#f2f2f2,stroke:#bdbdbd,stroke-width:1px,color:#333333;
    classDef purple fill:#f3e8ff,stroke:#7a4fb2,stroke-width:1px,color:#3a1f5a;
    classDef config fill:#f6f9ff,stroke:#6b9bf1,stroke-width:1px,color:#12418a;
    classDef cylinder fill:#fff7f0,stroke:#ff9f43,stroke-width:1px,color:#663300;
    classDef note fill:#fffceb,stroke:#e6c24a,stroke-width:1px,color:#6b4f00;
    classDef legend fill:#ffffff,stroke:#e6e6e6,stroke-width:1px,color:#333333;

    class Tests,PageObjects,POM,Actions,StateReaders,API,Node,BrowsersInstance blue
    class Locators,Helpers,ConfigLabel,PackageJSON,Lockfile gray
    class Node,API,BrowsersInstance green
    class SUT orange
    class Workflow,Dev,CI purple
    class Reports cylinder
    class S1,S2,S3,S4,S5 note

    %% Click events for mapped components
    click Tests "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/tests/todomvc.spec.js"
    click PageObjects "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/pages/todoPage.js"
    click ConfigLabel "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/playwright.config.js"
    click Workflow "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/.github/workflows/TodoMVC_Playwright.yml"
    click PackageJSON "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/package.json"
    click Lockfile "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/package-lock.json"
    click README "https://github.com/blessybabu-qa/todomvc_playwright/blob/main/README.md"
```
