eswarr11/playwright-ui-api

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.