# eswarr11/playwright-ui-api architecture

> Architecture diagram of the GitHub repository eswarr11/playwright-ui-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eswarr11/playwright-ui-api
- Repository: https://github.com/eswarr11/playwright-ui-api

## Overview

#### Purpose and Entry Points
This is a TypeScript Playwright automation repository for two external systems: SauceDemo UI and FakeStoreAPI cart endpoints. Primary local entry points are npm scripts backed by Playwright configuration: `playwright.config.ts` and `playwright.merge.config.ts`. CI orchestration is centralized in `.github/workflows/ci.yml`.

#### Test Execution Architecture
Playwright Test is the common runner for UI and API suites, enabling shared tagging, sharding, results, and reporting. UI specs begin under `ui/tests/`; API specs begin under `api/tests/carts/`. The suite is split by Playwright projects/configuration rather than a deployed application runtime.

Key boundaries:
- Browser-driven SauceDemo workflows: `ui/tests/`, `ui/pages/`
- HTTP-driven FakeStoreAPI validation: `api/tests/carts/`, `api/services/`
- Cross-cutting runner fixtures and helpers: `fixtures/ui.fixture.ts`, `helpers/`

#### UI Page-Object Layer
SauceDemo interaction is encapsulated in page objects and reusable components. `ui/pages/po-manager.ts` provides test-facing page-object access; pages inherit common navigation/action behavior from `ui/pages/base.page.ts`. Domain pages model login, inventory, cart, product detail, and checkout stages, including `ui/pages/inventory.page.ts`, `ui/pages/cart.page.ts`, and `ui/pages/checkout/step-one.page.ts`.

Tests should consume page objects through the UI fixture rather than instantiate browser logic directly: `fixtures/ui.fixture.ts`.

#### UI Interaction and Workflow Boundary
`helpers/pw-actions.ts` is the enforced UI action abstraction: page objects store selector DSL strings and route clicks, fills, and assertions through this layer. This separates stable SauceDemo locator conventions from test intent. Shared multistep cart/checkout workflows are composed in `ui/helpers/flow.helper.ts`; reusable shell behavior is isolated in `ui/components/header.component.ts` and `ui/components/burger-menu.component.ts`.

The external UI dependency is SauceDemo/Swag Labs, executed in Chromium locally and in Playwright container infrastructure in CI.

#### API Client, Auth, and Contracts
The API layer wraps FakeStoreAPI through service classes: `api/services/base.service.ts` establishes common HTTP behavior, `api/services/auth.service.ts` obtains JWTs, and `api/services/carts.service.ts` performs cart CRUD. Shared Axios client/auth plumbing resides in `helpers/api.client.ts` and `helpers/api-auth.util.ts`.

Runtime response contracts are defined with Zod in `api/schemas/cart.schema.ts`. API tests validate endpoint behavior, authorization boundaries, input validation, and contract snapshots; committed baseline shape is at `api/tests/carts/contract-snapshots/cart.snapshot.json`.

#### Authentication and State Lifecycle
Before UI execution, `global-setup.ts` creates reusable Playwright storage-state sessions for SauceDemo user types; `global-teardown.ts` handles suite cleanup. This is a deliberate lifecycle boundary: authenticated UI tests reuse persisted browser state rather than each performing login. API authentication is per test/client path through JWT attachment.

Known third-party product defects are intentionally represented as expected failures via `helpers/known-defects.helper.ts`; this preserves correct assertions while preventing accepted upstream defects from failing CI.

#### Reporting and CI Pipeline
CI runs quality gates, authentication setup, then independently sharded API and UI test jobs. Report aggregation is a final stage in `.github/workflows/ci.yml`. Blob reports are merged by `scripts/merge-playwright-report.js`; Allure generation is handled by `scripts/generate-allure-report.js`.

Material infrastructure is GitHub Actions, Node 24 for non-browser stages, Java 17 for Allure aggregation, and `mcr.microsoft.com/playwright:v1.61.1-noble` for browser jobs. The pipeline produces combined Playwright HTML and Allure artifacts rather than deploying a service.

Main entry points: [`.github/workflows/ci.yml`](https://github.com/eswarr11/playwright-ui-api/blob/main/.github/workflows/ci.yml) (GitHub Actions pipeline), [`playwright.config.ts`](https://github.com/eswarr11/playwright-ui-api/blob/main/playwright.config.ts) (Playwright configs), [`ui/pages/base.page.ts`](https://github.com/eswarr11/playwright-ui-api/blob/main/ui/pages/base.page.ts) (UI pages), [`api/services/carts.service.ts`](https://github.com/eswarr11/playwright-ui-api/blob/main/api/services/carts.service.ts) (Cart service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Execution & CI"]
  node_ci{{"GitHub Actions pipeline<br/>CI orchestration<br/>[ci.yml]"}}
  node_pw_config["Playwright configs<br/>runner configuration"]
  node_pw_merge_config["Report merge config<br/>runner configuration"]
  node_global_setup["UI session setup<br/>Playwright lifecycle<br/>[global-setup.ts]"]
  node_global_teardown["Suite teardown<br/>Playwright lifecycle<br/>[global-teardown.ts]"]
end

subgraph group_ui["UI Automation"]
  node_ui_tests["UI specs<br/>Playwright tests"]
  node_ui_fixture["UI fixture<br/>test fixture<br/>[ui.fixture.ts]"]
  node_po_manager["Page-object manager<br/>page-object access<br/>[po-manager.ts]"]
  node_ui_pages["UI pages<br/>page objects<br/>[base.page.ts]"]
  node_ui_flows["Cart checkout flows<br/>workflow helper<br/>[flow.helper.ts]"]
  node_saucedemo(("SauceDemo<br/>external UI"))
end

subgraph group_api["API Automation"]
  node_api_tests["Cart API specs<br/>Playwright tests"]
  node_cart_service["Cart service<br/>API service<br/>[carts.service.ts]"]
  node_auth_service["Auth service<br/>API service<br/>[auth.service.ts]"]
  node_cart_contract["Cart Zod contract<br/>runtime schema<br/>[cart.schema.ts]"]
  node_contract_snapshot["Cart contract baseline<br/>snapshot<br/>[cart.snapshot.json]"]
  node_fakestore(("FakeStoreAPI<br/>external API"))
end

subgraph group_shared["Shared Runtime"]
  node_pw_actions["UI action DSL<br/>interaction abstraction<br/>[pw-actions.ts]"]
  node_api_client["Axios auth client<br/>HTTP client<br/>[api.client.ts]"]
end

subgraph group_reporting["Reports"]
  node_blob_merge["Blob report merge<br/>report processor"]
  node_allure["Allure generation<br/>report processor"]
end

node_ci -->|"runs suites with"| node_pw_config
node_ci -->|"runs before UI"| node_global_setup
node_ci -->|"runs after suites"| node_global_teardown
node_pw_config -->|"selects projects"| node_ui_tests
node_pw_config -->|"selects projects"| node_api_tests
node_global_setup -->|"creates storage state from"| node_saucedemo
node_ui_tests -->|"uses"| node_ui_fixture
node_ui_fixture -->|"provides"| node_po_manager
node_po_manager -->|"accesses"| node_ui_pages
node_ui_pages -->|"uses"| node_pw_actions
node_ui_flows -->|"composes"| node_po_manager
node_ui_pages -->|"drives browser workflows"| node_saucedemo
node_api_tests -->|"exercises"| node_cart_service
node_cart_service -->|"uses authentication"| node_auth_service
node_cart_service -->|"sends requests through"| node_api_client
node_api_client -->|"calls"| node_fakestore
node_api_tests -->|"validates responses with"| node_cart_contract
node_api_tests -->|"compares against"| node_contract_snapshot
node_ci -->|"aggregates shard reports"| node_blob_merge
node_pw_merge_config -->|"configures"| node_blob_merge
node_blob_merge -->|"feeds combined results"| node_allure

click node_ci "https://github.com/eswarr11/playwright-ui-api/blob/main/.github/workflows/ci.yml"
click node_pw_config "https://github.com/eswarr11/playwright-ui-api/blob/main/playwright.config.ts"
click node_pw_merge_config "https://github.com/eswarr11/playwright-ui-api/blob/main/playwright.merge.config.ts"
click node_global_setup "https://github.com/eswarr11/playwright-ui-api/blob/main/global-setup.ts"
click node_global_teardown "https://github.com/eswarr11/playwright-ui-api/blob/main/global-teardown.ts"
click node_ui_fixture "https://github.com/eswarr11/playwright-ui-api/blob/main/fixtures/ui.fixture.ts"
click node_po_manager "https://github.com/eswarr11/playwright-ui-api/blob/main/ui/pages/po-manager.ts"
click node_ui_pages "https://github.com/eswarr11/playwright-ui-api/blob/main/ui/pages/base.page.ts"
click node_pw_actions "https://github.com/eswarr11/playwright-ui-api/blob/main/helpers/pw-actions.ts"
click node_ui_flows "https://github.com/eswarr11/playwright-ui-api/blob/main/ui/helpers/flow.helper.ts"
click node_cart_service "https://github.com/eswarr11/playwright-ui-api/blob/main/api/services/carts.service.ts"
click node_auth_service "https://github.com/eswarr11/playwright-ui-api/blob/main/api/services/auth.service.ts"
click node_api_client "https://github.com/eswarr11/playwright-ui-api/blob/main/helpers/api.client.ts"
click node_cart_contract "https://github.com/eswarr11/playwright-ui-api/blob/main/api/schemas/cart.schema.ts"
click node_contract_snapshot "https://github.com/eswarr11/playwright-ui-api/blob/main/api/tests/carts/contract-snapshots/cart.snapshot.json"
click node_blob_merge "https://github.com/eswarr11/playwright-ui-api/blob/main/scripts/merge-playwright-report.js"
click node_allure "https://github.com/eswarr11/playwright-ui-api/blob/main/scripts/generate-allure-report.js"

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_ci,node_pw_config,node_pw_merge_config,node_global_setup,node_global_teardown toneBlue
class node_ui_tests,node_ui_fixture,node_po_manager,node_ui_pages,node_ui_flows,node_saucedemo toneAmber
class node_api_tests,node_cart_service,node_auth_service,node_cart_contract,node_contract_snapshot,node_fakestore toneMint
class node_pw_actions,node_api_client toneRose
class node_blob_merge,node_allure toneIndigo
```

## Components

### Execution & CI

- [GitHub Actions pipeline](https://github.com/eswarr11/playwright-ui-api/blob/main/.github/workflows/ci.yml): CI orchestration · Runs gates, setup, sharded suites, and report aggregation. · `.github/workflows/ci.yml`
- [Playwright configs](https://github.com/eswarr11/playwright-ui-api/blob/main/playwright.config.ts): runner configuration · `playwright.config.ts`
- [Report merge config](https://github.com/eswarr11/playwright-ui-api/blob/main/playwright.merge.config.ts): runner configuration · `playwright.merge.config.ts`
- [UI session setup](https://github.com/eswarr11/playwright-ui-api/blob/main/global-setup.ts): Playwright lifecycle · Creates reusable SauceDemo storage states. · `global-setup.ts`
- [Suite teardown](https://github.com/eswarr11/playwright-ui-api/blob/main/global-teardown.ts): Playwright lifecycle · `global-teardown.ts`

### UI Automation

- **UI specs**: Playwright tests
- [UI fixture](https://github.com/eswarr11/playwright-ui-api/blob/main/fixtures/ui.fixture.ts): test fixture · Supplies tests with page-object access. · `fixtures/ui.fixture.ts`
- [Page-object manager](https://github.com/eswarr11/playwright-ui-api/blob/main/ui/pages/po-manager.ts): page-object access · `ui/pages/po-manager.ts`
- [UI pages](https://github.com/eswarr11/playwright-ui-api/blob/main/ui/pages/base.page.ts): page objects · Base, inventory, cart, and checkout page models. · `ui/pages/base.page.ts`
- [Cart checkout flows](https://github.com/eswarr11/playwright-ui-api/blob/main/ui/helpers/flow.helper.ts): workflow helper · `ui/helpers/flow.helper.ts`
- **SauceDemo**: external UI · Browser-driven Swag Labs dependency.

### API Automation

- **Cart API specs**: Playwright tests
- [Cart service](https://github.com/eswarr11/playwright-ui-api/blob/main/api/services/carts.service.ts): API service · Performs FakeStoreAPI cart CRUD. · `api/services/carts.service.ts`
- [Auth service](https://github.com/eswarr11/playwright-ui-api/blob/main/api/services/auth.service.ts): API service · Obtains JWTs for API requests. · `api/services/auth.service.ts`
- [Cart Zod contract](https://github.com/eswarr11/playwright-ui-api/blob/main/api/schemas/cart.schema.ts): runtime schema · `api/schemas/cart.schema.ts`
- [Cart contract baseline](https://github.com/eswarr11/playwright-ui-api/blob/main/api/tests/carts/contract-snapshots/cart.snapshot.json): snapshot · `api/tests/carts/contract-snapshots/cart.snapshot.json`
- **FakeStoreAPI**: external API

### Shared Runtime

- [UI action DSL](https://github.com/eswarr11/playwright-ui-api/blob/main/helpers/pw-actions.ts): interaction abstraction · Routes locator-based clicks, fills, and assertions. · `helpers/pw-actions.ts`
- [Axios auth client](https://github.com/eswarr11/playwright-ui-api/blob/main/helpers/api.client.ts): HTTP client · Shared request and JWT attachment plumbing. · `helpers/api.client.ts`

### Reports

- [Blob report merge](https://github.com/eswarr11/playwright-ui-api/blob/main/scripts/merge-playwright-report.js): report processor · `scripts/merge-playwright-report.js`
- [Allure generation](https://github.com/eswarr11/playwright-ui-api/blob/main/scripts/generate-allure-report.js): report processor · `scripts/generate-allure-report.js`

## Connections

- GitHub Actions pipeline → Playwright configs: runs suites with
- GitHub Actions pipeline → UI session setup: runs before UI
- GitHub Actions pipeline → Suite teardown: runs after suites
- Playwright configs → UI specs: selects projects
- Playwright configs → Cart API specs: selects projects
- UI session setup → SauceDemo: creates storage state from
- UI specs → UI fixture: uses
- UI fixture → Page-object manager: provides
- Page-object manager → UI pages: accesses
- UI pages → UI action DSL: uses
- Cart checkout flows → Page-object manager: composes
- UI pages → SauceDemo: drives browser workflows
- Cart API specs → Cart service: exercises
- Cart service → Auth service: uses authentication
- Cart service → Axios auth client: sends requests through
- Axios auth client → FakeStoreAPI: calls
- Cart API specs → Cart Zod contract: validates responses with
- Cart API specs → Cart contract baseline: compares against
- GitHub Actions pipeline → Blob report merge: aggregates shard reports
- Report merge config → Blob report merge: configures
- Blob report merge → Allure generation: feeds combined results