Pagewright

A Playwright + TypeScript test framework covering a web shop UI and a REST booking API, with typed page objects, fixtures and schema-checked API clients.

▶ Live test report

The Playwright HTML report from the latest CI run on main, republished after every push. Open a test to see its steps, or its trace to replay the run in your browser.

What's covered

The suite targets two public apps built for test practice:

• Sauce Demo for the UI.
• Restful Booker for the API.

Suite	Project	Tests	What it checks
Login	chromium	7	Standard user signs in; locked-out user, wrong password, unknown user and empty fields show the right error; protected pages redirect to login
Logout	chromium	1	Logging out returns to login and the old session can no longer open the inventory
Inventory	chromium	5	Every product and price is listed; all four sort options produce the correct order
Cart	chromium	5	Add and remove from the inventory and cart pages, badge count, cart order, cart survives a reload
Checkout	chromium	7	End-to-end order; item total, 8% tax and grand total for three baskets; required-field validation
Booking API	api	6	Create, read, search by name, replace (PUT), partial update (PATCH), delete
Booking contract	api	3	Raw responses match the zod schemas; schema rejects malformed data; missing bookings raise a typed error
Auth API	api	4	Token issued for valid credentials; bad credentials rejected; PUT, PATCH and DELETE refused without a valid token

That is 38 tests, plus one setup test that signs in once and saves the session.

Architecture

flowchart LR
    subgraph Tests
        UI[tests/ui/*.spec.ts]
        API[tests/api/*.spec.ts]
        Setup[tests/auth.setup.ts]
    end
    subgraph Fixtures
        F[src/fixtures<br/>page objects, API clients,<br/>token, seeded data, toMatchSchema]
    end
    subgraph Layer[Page objects and API clients]
        PO[src/pages<br/>LoginPage, InventoryPage,<br/>CartPage, Checkout pages]
        AC[src/api<br/>AuthClient, BookingClient,<br/>zod schemas]
    end
    Data[src/data<br/>builders and factories]
    Config[src/config<br/>dotenv + zod]

    UI --> F
    API --> F
    Setup --> F
    F --> PO
    F --> AC
    UI -.-> Data
    API -.-> Data
    PO --> SD[(Sauce Demo)]
    AC --> RB[(Restful Booker)]
    Config -.-> F

Loading

Design principles

• Tests read like specifications. Specs never touch selectors or HTTP details. They ask fixtures for page objects and clients and assert on behaviour.
• User-facing locators first. Page objects use getByRole wherever the app exposes a meaningful role and name, and fall back to getByTestId (data-test) for elements without one, such as prices and badges. There are no CSS chains or text= selectors.
• Web-first assertions, no sleeps. Every check uses auto-retrying expect on locators, so the suite waits for the app instead of for a timer.
• Sign in once. A setup project logs in and saves storageState; UI tests start authenticated. Login tests opt out with an empty state.
• Arrange through the fastest reliable path. Checkout pricing tests write the cart straight into localStorage through a seedCart fixture instead of clicking through the inventory, and API tests get a ready-made booking from the existingBooking fixture, which also cleans it up.
• Independent oracles. Expected prices come from a product catalog in src/data, not from the page under test. Money is handled in integer cents to avoid float rounding.
• Contracts are enforced, not assumed. Every API response is parsed with a strict zod schema, so a renamed or extra field fails loudly. Unexpected status codes raise an ApiError that carries the status and body.
• Isolated, parallel-safe data. Builders generate unique guest names, so tests can run in parallel on a shared public server.

Project structure

.
├── .github/workflows/ci.yml   # lint, typecheck, tests, report publishing
├── playwright.config.ts       # projects, reporters, retries, trace/video policy
├── src
│   ├── api                    # AuthClient, BookingClient, zod schemas, ApiError
│   ├── config                 # env parsing (dotenv + zod) and paths
│   ├── data                   # users, product catalog, customer factory, booking builder
│   ├── fixtures               # ui + api fixtures merged with mergeTests, custom matchers
│   ├── pages                  # page objects and shared components (header, product item)
│   └── utils                  # money parsing and formatting
└── tests
    ├── auth.setup.ts          # signs in once and saves storage state
    ├── api                    # booking CRUD, contract and auth tests
    └── ui                     # login, logout, inventory, cart, checkout

Run it locally

Requires Node.js 20 or newer (CI uses the version in .nvmrc).

git clone https://github.com/Raja9964/Pagewright.git
cd Pagewright
npm ci
npx playwright install chromium
npm test

No .env file is needed; the defaults point at the public demo apps. To override anything, copy the example and edit it:

cp .env.example .env

Running tests

Command	What it runs
npm test	Everything (setup, chromium and api)
npm run test:smoke	Tests tagged @smoke: the critical paths
npm run test:regression	Tests tagged @regression: the full suite
npm run test:ui	UI tests in Chromium
npm run test:api	API tests only (no browser needed)
npm run test:headed	UI tests in a visible browser
npm run report	Opens the last HTML report
npm run lint	ESLint with type-aware and Playwright rules
npm run typecheck	tsc --noEmit against the strict tsconfig
npm run format:check	Prettier check

Any Playwright CLI filter works too, for example npx playwright test --project=api --grep "PATCH".

Configuration

Settings are read from the environment (or a .env file) and validated with zod at startup. Blank values fall back to the defaults.

Variable	Default	Purpose
SAUCE_BASE_URL	https://www.saucedemo.com	UI base URL
SAUCE_USERNAME	standard_user	User for the shared login state
SAUCE_PASSWORD	secret_sauce	Password for all demo users
BOOKER_BASE_URL	https://restful-booker.herokuapp.com	API base URL
BOOKER_USERNAME	admin	API auth username
BOOKER_PASSWORD	password123	API auth password
CI	false	Enables retries, full traces, video and CI reporters

The demo credentials are published by the apps themselves, so they are safe to commit as defaults.

CI

.github/workflows/ci.yml runs on every push to main and every pull request:

1. Lint and typecheck: ESLint, Prettier check and tsc.
2. Playwright tests: installs Chromium and runs the whole suite.
3. Publish report (main only): deploys the HTML report to GitHub Pages. It runs even when tests fail, so the live report always shows the latest run.

When CI is set, Playwright retries failed tests twice, records a trace for every test, keeps screenshots and video for failures, and adds GitHub annotations.

Reports

• Live: the report from the latest run on main is hosted on GitHub Pages. Its Metadata panel links to the commit that was tested, and every test has a trace that opens in the browser.
• Locally: npm run report opens playwright-report/. Failed tests include the trace, a screenshot and, in CI, a video.
• In CI: the HTML report is uploaded as the playwright-report artifact on every run, whether it passes or fails. Download it from the workflow run, unzip it, and run npx playwright show-report <folder>.

License

MIT © 2026 Raja Mohamad