# unnamak/agentic-playwright-typescript-framework architecture

> Architecture diagram of the GitHub repository unnamak/agentic-playwright-typescript-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unnamak/agentic-playwright-typescript-framework
- Repository: https://github.com/unnamak/agentic-playwright-typescript-framework

## Overview

This repository is a Playwright/TypeScript automation framework for SauceDemo, with a principal user-to-result workflow of running page-object tests and receiving resilient actions plus test and healing reports. Its self-healing path intercepts failed locator actions, checks a persistent selector cache, inspects the live DOM, consults an optional LLM or semantic heuristics, verifies a candidate, retries the action, and records healing events. Page-object coverage includes login, inventory/cart and checkout. The graph follows README capabilities and sampled call ownership; unsampled fixture, page-object and reporter wiring is represented only where documented.

Main entry points: [`tests`](https://github.com/unnamak/agentic-playwright-typescript-framework/tree/main/tests) (Playwright suites), [`src/core/agent/HealerAgent.ts`](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/HealerAgent.ts) (Healing orchestrator), [`src/pages/BasePage.ts`](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/BasePage.ts) (Page base), [`src/core/wrapper/SmartLocator.ts`](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/wrapper/SmartLocator.ts) (Smart locator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_test_flow["Test workflow"]
  node_playwright_tests["Playwright suites"]
  node_fixtures["Smart fixtures<br/>[test.fixture.ts]"]
  node_test_data["Test data<br/>[testData.ts]"]
end

subgraph group_healing["Self-healing"]
  node_smart_page["Smart page<br/>[SmartPage.ts]"]
  node_smart_locator["Smart locator<br/>[SmartLocator.ts]"]
  node_healer["Healing orchestrator<br/>[HealerAgent.ts]"]
  node_dom["DOM extractor<br/>[DomExtractor.ts]"]
  node_heuristics["Semantic matching<br/>[HeuristicEngine.ts]"]
  node_llm["LLM provider<br/>[LlmProvider.ts]"]
  node_config["Runtime configuration<br/>[config.ts]"]
end

subgraph group_evidence["Healing evidence"]
  node_cache[("Selector cache<br/>[HealingCache.ts]")]
  node_events["Healing events<br/>[HealerAgent.ts]"]
  node_reporter["Healing dashboard<br/>[HealingReporter.ts]"]
end

subgraph group_domain_pages["SauceDemo pages"]
  node_login_page["Login page<br/>[LoginPage.ts]"]
  node_inventory_page["Inventory page<br/>[InventoryPage.ts]"]
  node_cart_page["Cart page<br/>[CartPage.ts]"]
  node_checkout_one["Checkout details"]
  node_checkout_two["Checkout summary"]
  node_checkout_done["Order complete"]
  node_base_page["Page base<br/>[BasePage.ts]"]
end

node_engineer(("Test author"))
node_saucedemo(("SauceDemo site"))
node_llm_services(("LLM services"))
node_reports["Report files"]

node_engineer -->|"authors tests"| node_playwright_tests
node_playwright_tests -->|"runs with"| node_fixtures
node_fixtures -->|"provides"| node_smart_page
node_playwright_tests -->|"uses data"| node_test_data
node_playwright_tests -->|"exercises"| node_login_page
node_playwright_tests -->|"exercises"| node_inventory_page
node_playwright_tests -->|"exercises"| node_cart_page
node_playwright_tests -->|"exercises"| node_checkout_one
node_playwright_tests -->|"exercises"| node_checkout_two
node_playwright_tests -->|"exercises"| node_checkout_done
node_login_page -->|"extends"| node_base_page
node_inventory_page -->|"extends"| node_base_page
node_cart_page -->|"extends"| node_base_page
node_checkout_one -->|"extends"| node_base_page
node_checkout_two -->|"extends"| node_base_page
node_checkout_done -->|"extends"| node_base_page
node_base_page -->|"uses"| node_smart_page
node_smart_page -->|"creates"| node_smart_locator
node_smart_locator -->|"invokes on failure"| node_healer
node_healer -->|"reads settings"| node_config
node_healer -->|"checks and updates"| node_cache
node_healer -->|"extracts snapshot"| node_dom
node_healer -.->|"consults by strategy"| node_llm
node_healer -->|"scores candidates"| node_heuristics
node_healer -->|"records events"| node_events
node_dom -->|"inspects live DOM"| node_saucedemo
node_smart_locator -->|"performs and retries actions"| node_saucedemo
node_llm -.->|"requests candidates"| node_llm_services
node_reporter -->|"reads events"| node_events
node_reporter -->|"writes dashboard"| node_reports

click node_playwright_tests "https://github.com/unnamak/agentic-playwright-typescript-framework/tree/main/tests"
click node_fixtures "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/fixtures/test.fixture.ts"
click node_test_data "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/data/testData.ts"
click node_login_page "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/LoginPage.ts"
click node_inventory_page "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/InventoryPage.ts"
click node_cart_page "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/CartPage.ts"
click node_checkout_one "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/CheckoutStepOnePage.ts"
click node_checkout_two "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/CheckoutStepTwoPage.ts"
click node_checkout_done "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/CheckoutCompletePage.ts"
click node_base_page "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/BasePage.ts"
click node_smart_page "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/wrapper/SmartPage.ts"
click node_smart_locator "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/wrapper/SmartLocator.ts"
click node_healer "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/HealerAgent.ts"
click node_dom "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/DomExtractor.ts"
click node_heuristics "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/HeuristicEngine.ts"
click node_llm "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/LlmProvider.ts"
click node_cache "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/cache/HealingCache.ts"
click node_events "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/HealerAgent.ts"
click node_reporter "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/reporter/HealingReporter.ts"
click node_config "https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/utils/config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_playwright_tests,node_fixtures,node_test_data toneBlue
class node_smart_page,node_smart_locator,node_healer,node_dom,node_heuristics,node_llm,node_config toneAmber
class node_cache,node_events,node_reporter toneMint
class node_login_page,node_inventory_page,node_cart_page,node_checkout_one,node_checkout_two,node_checkout_done,node_base_page toneRose
class node_engineer,node_saucedemo,node_llm_services,node_reports toneIndigo
```

## Components

### Test workflow

- [Playwright suites](https://github.com/unnamak/agentic-playwright-typescript-framework/tree/main/tests): `tests`
- [Smart fixtures](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/fixtures/test.fixture.ts): `src/fixtures/test.fixture.ts`
- [Test data](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/data/testData.ts): `src/data/testData.ts`

### Self-healing

- [Smart page](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/wrapper/SmartPage.ts): `src/core/wrapper/SmartPage.ts`
- [Smart locator](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/wrapper/SmartLocator.ts): `src/core/wrapper/SmartLocator.ts`
- [Healing orchestrator](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/HealerAgent.ts): `src/core/agent/HealerAgent.ts`
- [DOM extractor](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/DomExtractor.ts): `src/core/agent/DomExtractor.ts`
- [Semantic matching](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/HeuristicEngine.ts): `src/core/agent/HeuristicEngine.ts`
- [LLM provider](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/LlmProvider.ts): `src/core/agent/LlmProvider.ts`
- [Runtime configuration](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/utils/config.ts): `src/utils/config.ts`

### Healing evidence

- [Selector cache](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/cache/HealingCache.ts): `src/core/cache/HealingCache.ts`
- [Healing events](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/agent/HealerAgent.ts): `src/core/agent/HealerAgent.ts`
- [Healing dashboard](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/core/reporter/HealingReporter.ts): `src/core/reporter/HealingReporter.ts`

### SauceDemo pages

- [Login page](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/LoginPage.ts): `src/pages/LoginPage.ts`
- [Inventory page](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/InventoryPage.ts): `src/pages/InventoryPage.ts`
- [Cart page](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/CartPage.ts): `src/pages/CartPage.ts`
- [Checkout details](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/CheckoutStepOnePage.ts): `src/pages/CheckoutStepOnePage.ts`
- [Checkout summary](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/CheckoutStepTwoPage.ts): `src/pages/CheckoutStepTwoPage.ts`
- [Order complete](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/CheckoutCompletePage.ts): `src/pages/CheckoutCompletePage.ts`
- [Page base](https://github.com/unnamak/agentic-playwright-typescript-framework/blob/main/src/pages/BasePage.ts): `src/pages/BasePage.ts`

### Other components

- **Test author**
- **SauceDemo site**
- **LLM services**
- **Report files**

## Connections

- Test author → Playwright suites: authors tests
- Playwright suites → Smart fixtures: runs with
- Smart fixtures → Smart page: provides
- Playwright suites → Test data: uses data
- Playwright suites → Login page: exercises
- Playwright suites → Inventory page: exercises
- Playwright suites → Cart page: exercises
- Playwright suites → Checkout details: exercises
- Playwright suites → Checkout summary: exercises
- Playwright suites → Order complete: exercises
- Login page → Page base: extends
- Inventory page → Page base: extends
- Cart page → Page base: extends
- Checkout details → Page base: extends
- Checkout summary → Page base: extends
- Order complete → Page base: extends
- Page base → Smart page: uses
- Smart page → Smart locator: creates
- Smart locator → Healing orchestrator: invokes on failure
- Healing orchestrator → Runtime configuration: reads settings
- Healing orchestrator → Selector cache: checks and updates
- Healing orchestrator → DOM extractor: extracts snapshot
- Healing orchestrator → LLM provider: consults by strategy
- Healing orchestrator → Semantic matching: scores candidates
- Healing orchestrator → Healing events: records events
- DOM extractor → SauceDemo site: inspects live DOM
- Smart locator → SauceDemo site: performs and retries actions
- LLM provider → LLM services: requests candidates
- Healing dashboard → Healing events: reads events
- Healing dashboard → Report files: writes dashboard