How marcoveraz/playwright-typescript-framework works
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: pages.fixture.ts Pages fixture · saucedemo UI specs · posts.client.ts Posts client · playwright.config.ts Playwright
Components 23
Execution
Playwright runner, scripts, and CI workflow that execute the suite
- Playwright · Main test runner configuration and execution entrypoint
playwright.config.ts - CI workflow · GitHub Actions pipeline for running Playwright tests and publishing artifacts
.github/workflows/playwright.yml - Scripts · Package scripts and dependency entrypoint for local execution
package.json
UI Automation
Sauce Demo browser automation stack
- UI specs · End-to-end Sauce Demo scenarios
tests/ui/saucedemo - Pages fixture · Injects page objects into UI tests
src/fixtures/saucedemo/pages.fixture.ts - Auth fixture · Authentication setup for Sauce Demo tests
src/fixtures/saucedemo/auth.fixture.ts - Base fixture · Shared UI fixture foundation
src/fixtures/saucedemo/base.fixture.ts - Login page · Handles Sauce Demo login interactions
src/pages/saucedemo/LoginPage.ts - Inventory · Product listing and add-to-cart interactions
src/pages/saucedemo/InventoryPage.ts - Cart page · Shopping cart view and item review
src/pages/saucedemo/ShoppingCartPage.ts - Checkout info · Checkout information form
src/pages/saucedemo/CheckoutYourInformationPage.ts - Overview page · Checkout summary and order review
src/pages/saucedemo/CheckoutOverviewPage.ts - Complete page · Order completion confirmation screen
src/pages/saucedemo/CheckoutCompletePage.ts - Header menu · Common navigation and header actions
src/pages/saucedemo/HeaderMenuPage.ts
API Automation
JSONPlaceholder HTTP automation stack
- API specs · JSONPlaceholder API behavior tests
tests/api/jsonplaceholder/posts.spec.ts - API fixture · Provides API client access to tests
src/api/fixtures/jsonplaceholder/api.fixture.ts - Posts client · Request client for JSONPlaceholder posts
src/api/clients/jsonplaceholder/posts.client.ts - Base API · Shared API client foundation
src/api/base.api.ts - Post payloads · Outbound payload shaping for post requests
src/api/payloads/jsonplaceholder/posts.ts - Post model · Expected response contract for JSONPlaceholder posts
src/api/models/jsonplaceholder/post.model.ts
Shared Core
Reusable models, utilities, and environment configuration
- UI models · Structured product models used across UI assertions
src/models/saucedemo - UI utils · Reusable browser-test helpers for products, waits, and general utilities
src/utils - Env config · Runtime environment selection and shared Sauce Demo settings
src/config/saucedemo
Connections 26
- 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