# marcoveraz/playwright-typescript-framework architecture

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

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

## Overview

1. This repository is a Playwright + TypeScript automation framework, not an application under test. Its architecture is split into two independent test domains: UI automation for Sauce Demo and API automation for JSONPlaceholder.

2. The main orchestration layer is Playwright itself, driven by `playwright.config.ts`, package scripts, and the GitHub Actions workflow in `.github/workflows/playwright.yml`. Those pieces define how tests are executed locally and in CI, and how artifacts like traces, screenshots, videos, and reports are produced.

3. The UI automation stack lives under `src/pages/saucedemo`, `src/fixtures/saucedemo`, `src/models/saucedemo`, `src/config/saucedemo`, and `src/utils`. This is the classic Page Object Model boundary: specs call page objects, page objects encapsulate browser interactions, and fixtures wire those objects into tests.

4. The Sauce Demo configuration layer supports multi-environment execution. `src/config/saucedemo/environments/{dev,qa,stage,prod}.ts`, together with `env.ts` and `globals.ts`, map the `ENV` runtime variable to the target base URL and shared settings. This is the main environment-switching mechanism in the repo.

5. UI page objects represent each major screen in the purchase flow: login, inventory, cart, checkout information, checkout overview, checkout complete, and header navigation. The tests in `tests/ui/saucedemo` compose these pages into end-to-end user journeys rather than interacting with the browser directly.

6. The UI domain models under `src/models/saucedemo` capture structured product data used across pages and assertions. These models help keep comparisons and cross-page validations consistent, especially for inventory, cart, and checkout summary checks.

7. Shared UI utilities in `src/utils` provide reusable browser-test helpers such as product handling, general utilities, and wait helpers. These act as the non-page support layer that keeps page objects smaller and reduces duplicated test logic.

8. The API automation stack is separate and centered under `src/api`. It has its own base client (`base.api.ts`), request clients in `src/api/clients/jsonplaceholder`, fixtures in `src/api/fixtures/jsonplaceholder`, payload builders in `src/api/payloads/jsonplaceholder`, and response models in `src/api/models/jsonplaceholder`.

9. The API design follows a clear request/response boundary: specs use client classes, clients depend on the base API layer, payload builders shape outbound data, and models define the expected response contract. This separation makes the API tests reusable and easier to extend beyond the current `posts` coverage.

10. The test layer is split cleanly by concern: `tests/ui/saucedemo` covers login and shopping-process flows, while `tests/api/jsonplaceholder/posts.spec.ts` covers API behavior. That separation is important for diagramming because UI and API tests do not share the same execution path or supporting abstractions.

11. Data flow in the UI path is: test spec -> fixtures -> page objects -> runtime config/environment -> browser -> assertions using models/utilities. The result is a layered browser automation flow with the test files acting as scenario definitions, not as interaction code.

12. Data flow in the API path is: test spec -> API fixture/client -> payload/model layer -> external JSONPlaceholder service -> response assertions. This is a direct HTTP integration path, distinct from the browser-driven UI path.

13. Supporting repository structure includes `.github` for workflow and ownership metadata, `package.json`/`package-lock.json` for dependencies and scripts, and `tsconfig.json` for TypeScript compilation settings. These are enabling layers around the framework rather than test logic itself.

14. In diagram terms, the important boundaries are: execution/orchestration, UI automation, API automation, shared utilities/models, and environment configuration. The repo is intentionally organized so that the UI and API stacks can evolve independently while sharing the same Playwright/TypeScript test runner.

Main entry points: [`src/fixtures/saucedemo/pages.fixture.ts`](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/fixtures/saucedemo/pages.fixture.ts) (Pages fixture), [`tests/ui/saucedemo`](https://github.com/marcoveraz/playwright-typescript-framework/tree/main/tests/ui/saucedemo) (UI specs), [`src/api/clients/jsonplaceholder/posts.client.ts`](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/clients/jsonplaceholder/posts.client.ts) (Posts client), [`playwright.config.ts`](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/playwright.config.ts) (Playwright)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Execution"]
  node_playwright_runner["Playwright<br/>runner/config"]
  node_ci_workflow["CI workflow<br/>github actions<br/>[playwright.yml]"]
  node_package_scripts["Scripts<br/>npm manifest<br/>[package.json]"]
end

subgraph group_ui["UI Automation"]
  node_ui_specs["UI specs<br/>test suite"]
  node_pages_fixture["Pages fixture<br/>fixture wiring<br/>[pages.fixture.ts]"]
  node_auth_fixture["Auth fixture<br/>fixture wiring<br/>[auth.fixture.ts]"]
  node_base_fixture["Base fixture<br/>fixture base<br/>[base.fixture.ts]"]
  node_login_page["Login page<br/>page object<br/>[LoginPage.ts]"]
  node_inventory_page["Inventory<br/>page object<br/>[InventoryPage.ts]"]
  node_cart_page["Cart page<br/>page object"]
  node_checkout_info_page["Checkout info<br/>page object"]
  node_checkout_overview_page["Overview page<br/>page object"]
  node_checkout_complete_page["Complete page<br/>page object"]
  node_header_menu_page["Header menu<br/>page object<br/>[HeaderMenuPage.ts]"]
end

subgraph group_api["API Automation"]
  node_api_specs["API specs<br/>test suite<br/>[posts.spec.ts]"]
  node_api_fixture["API fixture<br/>fixture wiring<br/>[api.fixture.ts]"]
  node_posts_client["Posts client<br/>api client<br/>[posts.client.ts]"]
  node_api_base["Base API<br/>http core<br/>[base.api.ts]"]
  node_posts_payloads["Post payloads<br/>request builders<br/>[posts.ts]"]
  node_post_model["Post model<br/>response model<br/>[post.model.ts]"]
end

subgraph group_shared["Shared Core"]
  node_ui_models["UI models<br/>domain models"]
  node_ui_utils["UI utils<br/>helpers"]
  node_ui_config["Env config<br/>env mapping"]
end

node_package_scripts -->|"runs"| node_playwright_runner
node_ci_workflow -->|"executes"| node_playwright_runner
node_playwright_runner -->|"discovers"| node_ui_specs
node_playwright_runner -->|"discovers"| node_api_specs
node_ui_specs -->|"uses"| node_pages_fixture
node_ui_specs -->|"uses"| node_auth_fixture
node_pages_fixture -->|"builds on"| node_base_fixture
node_pages_fixture -->|"injects"| node_login_page
node_pages_fixture -->|"injects"| node_inventory_page
node_pages_fixture -->|"injects"| node_cart_page
node_pages_fixture -->|"injects"| node_checkout_info_page
node_pages_fixture -->|"injects"| node_checkout_overview_page
node_pages_fixture -->|"injects"| node_checkout_complete_page
node_pages_fixture -->|"injects"| node_header_menu_page
node_inventory_page -->|"reads"| node_ui_models
node_cart_page -->|"reads"| node_ui_models
node_checkout_overview_page -->|"reads"| node_ui_models
node_inventory_page -->|"uses"| node_ui_utils
node_cart_page -->|"uses"| node_ui_utils
node_ui_config -->|"configures"| node_login_page
node_ui_specs -->|"depends on"| node_ui_config
node_api_specs -->|"uses"| node_api_fixture
node_api_fixture -->|"provides"| node_posts_client
node_posts_client -->|"extends"| node_api_base
node_posts_client -->|"uses"| node_posts_payloads
node_posts_client -->|"validates"| node_post_model

click node_playwright_runner "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/playwright.config.ts"
click node_ci_workflow "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/.github/workflows/playwright.yml"
click node_package_scripts "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/package.json"
click node_ui_specs "https://github.com/marcoveraz/playwright-typescript-framework/tree/main/tests/ui/saucedemo"
click node_pages_fixture "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/fixtures/saucedemo/pages.fixture.ts"
click node_auth_fixture "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/fixtures/saucedemo/auth.fixture.ts"
click node_base_fixture "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/fixtures/saucedemo/base.fixture.ts"
click node_login_page "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/LoginPage.ts"
click node_inventory_page "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/InventoryPage.ts"
click node_cart_page "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/ShoppingCartPage.ts"
click node_checkout_info_page "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/CheckoutYourInformationPage.ts"
click node_checkout_overview_page "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/CheckoutOverviewPage.ts"
click node_checkout_complete_page "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/CheckoutCompletePage.ts"
click node_header_menu_page "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/HeaderMenuPage.ts"
click node_ui_models "https://github.com/marcoveraz/playwright-typescript-framework/tree/main/src/models/saucedemo"
click node_ui_utils "https://github.com/marcoveraz/playwright-typescript-framework/tree/main/src/utils"
click node_ui_config "https://github.com/marcoveraz/playwright-typescript-framework/tree/main/src/config/saucedemo"
click node_api_specs "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/tests/api/jsonplaceholder/posts.spec.ts"
click node_api_fixture "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/fixtures/jsonplaceholder/api.fixture.ts"
click node_posts_client "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/clients/jsonplaceholder/posts.client.ts"
click node_api_base "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/base.api.ts"
click node_posts_payloads "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/payloads/jsonplaceholder/posts.ts"
click node_post_model "https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/models/jsonplaceholder/post.model.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_runner,node_ci_workflow,node_package_scripts toneBlue
class node_ui_specs,node_pages_fixture,node_auth_fixture,node_base_fixture,node_login_page,node_inventory_page,node_cart_page,node_checkout_info_page,node_checkout_overview_page,node_checkout_complete_page,node_header_menu_page toneAmber
class node_api_specs,node_api_fixture,node_posts_client,node_api_base,node_posts_payloads,node_post_model toneMint
class node_ui_models,node_ui_utils,node_ui_config toneRose
```

## Components

### Execution

Playwright runner, scripts, and CI workflow that execute the suite

- [Playwright](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/playwright.config.ts): runner/config · Main test runner configuration and execution entrypoint · `playwright.config.ts`
- [CI workflow](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/.github/workflows/playwright.yml): github actions · GitHub Actions pipeline for running Playwright tests and publishing artifacts · `.github/workflows/playwright.yml`
- [Scripts](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/package.json): npm manifest · Package scripts and dependency entrypoint for local execution · `package.json`

### UI Automation

Sauce Demo browser automation stack

- [UI specs](https://github.com/marcoveraz/playwright-typescript-framework/tree/main/tests/ui/saucedemo): test suite · End-to-end Sauce Demo scenarios · `tests/ui/saucedemo`
- [Pages fixture](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/fixtures/saucedemo/pages.fixture.ts): fixture wiring · Injects page objects into UI tests · `src/fixtures/saucedemo/pages.fixture.ts`
- [Auth fixture](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/fixtures/saucedemo/auth.fixture.ts): fixture wiring · Authentication setup for Sauce Demo tests · `src/fixtures/saucedemo/auth.fixture.ts`
- [Base fixture](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/fixtures/saucedemo/base.fixture.ts): fixture base · Shared UI fixture foundation · `src/fixtures/saucedemo/base.fixture.ts`
- [Login page](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/LoginPage.ts): page object · Handles Sauce Demo login interactions · `src/pages/saucedemo/LoginPage.ts`
- [Inventory](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/InventoryPage.ts): page object · Product listing and add-to-cart interactions · `src/pages/saucedemo/InventoryPage.ts`
- [Cart page](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/ShoppingCartPage.ts): page object · Shopping cart view and item review · `src/pages/saucedemo/ShoppingCartPage.ts`
- [Checkout info](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/CheckoutYourInformationPage.ts): page object · Checkout information form · `src/pages/saucedemo/CheckoutYourInformationPage.ts`
- [Overview page](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/CheckoutOverviewPage.ts): page object · Checkout summary and order review · `src/pages/saucedemo/CheckoutOverviewPage.ts`
- [Complete page](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/CheckoutCompletePage.ts): page object · Order completion confirmation screen · `src/pages/saucedemo/CheckoutCompletePage.ts`
- [Header menu](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/pages/saucedemo/HeaderMenuPage.ts): page object · Common navigation and header actions · `src/pages/saucedemo/HeaderMenuPage.ts`

### API Automation

JSONPlaceholder HTTP automation stack

- [API specs](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/tests/api/jsonplaceholder/posts.spec.ts): test suite · JSONPlaceholder API behavior tests · `tests/api/jsonplaceholder/posts.spec.ts`
- [API fixture](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/fixtures/jsonplaceholder/api.fixture.ts): fixture wiring · Provides API client access to tests · `src/api/fixtures/jsonplaceholder/api.fixture.ts`
- [Posts client](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/clients/jsonplaceholder/posts.client.ts): api client · Request client for JSONPlaceholder posts · `src/api/clients/jsonplaceholder/posts.client.ts`
- [Base API](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/base.api.ts): http core · Shared API client foundation · `src/api/base.api.ts`
- [Post payloads](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/payloads/jsonplaceholder/posts.ts): request builders · Outbound payload shaping for post requests · `src/api/payloads/jsonplaceholder/posts.ts`
- [Post model](https://github.com/marcoveraz/playwright-typescript-framework/blob/main/src/api/models/jsonplaceholder/post.model.ts): response model · Expected response contract for JSONPlaceholder posts · `src/api/models/jsonplaceholder/post.model.ts`

### Shared Core

Reusable models, utilities, and environment configuration

- [UI models](https://github.com/marcoveraz/playwright-typescript-framework/tree/main/src/models/saucedemo): domain models · Structured product models used across UI assertions · `src/models/saucedemo`
- [UI utils](https://github.com/marcoveraz/playwright-typescript-framework/tree/main/src/utils): helpers · Reusable browser-test helpers for products, waits, and general utilities · `src/utils`
- [Env config](https://github.com/marcoveraz/playwright-typescript-framework/tree/main/src/config/saucedemo): env mapping · Runtime environment selection and shared Sauce Demo settings · `src/config/saucedemo`

## Connections

- Scripts → Playwright: runs · npm scripts invoke the Playwright configuration
- CI workflow → Playwright: executes · CI uses the same Playwright runner and config
- Playwright → UI specs: discovers · Runner collects UI specs for execution
- Playwright → API specs: discovers · Runner collects API specs for execution
- UI specs → Pages fixture: uses · UI tests consume page-object fixtures
- UI specs → Auth fixture: uses · UI tests can reuse auth setup
- Pages fixture → Base fixture: builds on · Page fixture extends the shared UI fixture base
- Pages fixture → Login page: injects · Fixtures provide the login page object
- Pages fixture → Inventory: injects · Fixtures provide the inventory page object
- Pages fixture → Cart page: injects · Fixtures provide the cart page object
- Pages fixture → Checkout info: injects · Fixtures provide the checkout information page object
- Pages fixture → Overview page: injects · Fixtures provide the checkout overview page object
- Pages fixture → Complete page: injects · Fixtures provide the completion page object
- Pages fixture → Header menu: injects · Fixtures provide the shared header menu page object
- Inventory → UI models: reads · Inventory interactions use product models
- Cart page → UI models: reads · Cart checks use structured product data
- Overview page → UI models: reads · Overview assertions use product summaries
- Inventory → UI utils: uses · Page objects rely on shared UI helpers
- Cart page → UI utils: uses · Page objects rely on shared UI helpers
- Env config → Login page: configures · Environment settings drive browser targets and page behavior
- UI specs → Env config: depends on · UI scenarios resolve runtime environment before execution
- API specs → API fixture: uses · API tests consume the API fixture
- API fixture → Posts client: provides · Fixture exposes the posts client to tests
- Posts client → Base API: extends · Client builds on the shared API foundation
- Posts client → Post payloads: uses · Client shapes request bodies from payload builders
- Posts client → Post model: validates · Client responses are checked against response models
