Playwright IA Automation Framework — Saucedemo

An end-to-end test framework where a Jira ticket becomes a reviewed, TCMS-mirrored Playwright pull request — authored by AI agents, gated by deterministic CI. Built on saucedemo as both a reusable template and a portfolio piece.

overview

The framework is code-first and AI-extended. Tests are plain, fast, deterministic Playwright + TypeScript — nothing exotic at runtime. The "AI" part is the _authoring_ layer: a set of custom Claude Code skills read a Jira ticket, generate Page-Object-backed tests, run them, and open a GitHub PR — optionally mirroring each test into a Qase TCMS so non-technical reviewers can browse human-readable cases. A human reviews and merges; CI keeps everything honest.

How it works — the pipeline

The whole system, top-down: a ticket goes in one end, a reviewed-and-mirrored test comes out the other.

flowchart LR
    J["Jira ticket<br/>(project SW)"] -->|"/refine-ticket"| R["Hardened<br/>acceptance criteria"]
    R -->|"/from-issue"| G["Tests + Page Objects<br/>+ TCMS record"]
    G --> PR["GitHub Pull Request"]
    PR -->|"CI: changed specs only<br/>+ typecheck + strict lint"| Rev["Human review"]
    Rev -->|merge| M["main"]
    M -->|"CI: full suite<br/>+ catalog sync"| Q["Qase TCMS<br/>(human-readable cases)"]

1. `/refine-ticket` hardens a Jira ticket's acceptance criteria against a "bulletproof" rubric (grounded in the existing automation + app docs) and writes the refined ACs back to Jira — so the next step has nothing to guess.
2. `/from-issue` reads the refined ticket through the Atlassian MCP, generates tests + Page Objects (scaffolding new ones via /scaffold-page-object, verifying selectors live via playwright-cli), runs them, writes a committed TCMS record, and opens a GitHub PR.
3. CI on the PR runs only the spec files that PR changed + a typecheck + strict-lint gate — fast, focused feedback.
4. A human reviews and merges — the PR is the review gate.
5. CI on merge runs the full suite, syncs the catalog to Qase, and commits the refreshed id map back — so the mirror stays accurate with zero manual steps.

Highlights

• 🎫 Ticket-to-PR automation — /from-issue SW-123 turns a Jira story into a passing, reviewed Playwright PR.
• 🧩 Composed Page Objects — strict Page Object + Component model (Header, Footer, CartBadge, BurgerMenu) with enforced composition rules.
• 🔐 Data-driven auth matrix — Playwright projects derive from a single AUTH_USERS array; the toolchain grows the matrix one user at a time, only as tickets need it.
• 🗂️ Opt-in TCMS mirror — one-way code→Qase sync at merge: human-readable cases with steps, per-case Jira provenance, and an auto-maintained id map.
• ⚡ Smart CI — PRs run only their changed specs; merges run the full suite; a typecheck + --max-warnings 0 lint gate blocks regressions before they land.
• 🌐 Config-driven — base URL, credentials, and TCMS settings come from env; point it at a different app without touching code.
• 📚 Documented decisions — every architectural choice is an ADR; the AI rules live in CLAUDE.md.

Tech stack

The AI-assisted workflow (skills)

The authoring layer is four composable Claude Code skills. They build on each other top-down:

refined Jira ticket

/from-issue is the conductor: it calls /scaffold-page-object when a Page Object doesn't exist yet, uses playwright-cli to confirm selectors, grows the auth harness when a ticket needs an unwired user, and surfaces every assumption it made in the PR body for the reviewer.

📋 See a real example → PR #25 — _automate SW-11 burger menu scenarios_ is an actual /from-issue pull request from this repo. Its description carries the auto-generated "What I understood" summary, the AC-coverage table, the ⚠️ Assumptions the agent flagged for review, and the verification results — exactly what a reviewer reads before merging.

generated-pr

Architecture

Strict, one-directional composition: tests know Pages; Pages compose Components; Components hold Locators. Tests never touch a raw Locator.

flowchart TD
    Spec["Spec — one per feature<br/>tests/.../*.spec.ts"] -->|"imports test/expect"| Fix["Fixture — @fixtures/test<br/>(injects ready Page Objects)"]
    Fix --> Pages
    subgraph Pages["Page Objects — src/pages"]
        LP[LoginPage]
        IP[InventoryPage]
        CP[CartPage]
        CK["checkout/ — Info · Overview · Complete"]
    end
    Pages -->|compose| Comps
    subgraph Comps["Components — src/components"]
        H[Header]
        F[Footer]
        CB[CartBadge]
        BM[BurgerMenu]
    end
    Comps -->|hold| Loc["Locators — data-test / getByRole"]
    Pages -.->|"page-direct locators"| Loc

Key ideas:

• Composition rules are enforced — e.g. Pages never return other Pages, queries return data (never Locator), component nesting depth ≤ 2. The full list is in CLAUDE.md and docs/architecture.md.
• Fixtures inject ready Page Objects — specs import { test, expect } from '@fixtures/test' and receive loginPage, inventoryPage, … pre-wired.
• Data-driven projects — playwright.config.ts derives its projects from tests/users.ts AUTH_USERS (['standard', 'problem'] today). Each user yields a setup-<user> (storageState) + chromium-<user> project, plus chromium-no-auth. New users wire in on demand; cross-browser is a deliberate separate decision (ADR-0004).
• Role tags route tests to projects — @no-auth, @standard, @problem, @all-users, @smoke (see the tag table in CLAUDE.md).

Coverage so far: login · inventory (content + sort) · footer · cart · checkout (information → overview → complete) · logout · burger menu.

TCMS mirror (Qase)

An opt-in, one-way mirror so non-technical reviewers can browse human-readable cases. Off unless QASE_* is configured.

• At merge, CI runs tcms:sync — it creates/updates/archives Qase cases (suite tree feature › context › bucket, steps from test.step, expected result = the ticket's AC text, per-case Jira provenance) and commits the refreshed qase-map.json (the test→case id index) back to the branch. No run is created — merges stay noise-free.
• Runs are explicit — npm run qase:smoke / qase:regression execute a scope _and_ record a labeled Qase run; tcms:run records an ad-hoc run from the last results.
• Swappable — src/tcms/qase-client.ts is the only Qase-aware file; it implements a tool-agnostic seam, so Xray/Zephyr/etc. is a sibling client. Full design in docs/tcms.md.

qase board

Continuous integration

One workflow (.github/workflows/test.yml), two behaviors:

The "changed specs only" selection is a deliberate choice over Playwright's --only-changed (which follows the import graph and re-runs the world when a shared fixture changes) — the full suite on merge is the real integration gate.

Getting started

Prerequisites

• Node.js 22.x or newer · git · ~300 MB free disk for the Chromium browser

Install & run

git clone https://github.com/Diegocortes15/playwright-ia-automation-framework-saucedemo.git
cd playwright-ia-automation-framework-saucedemo
npm install
npx playwright install chromium
cp .env.example .env          # baseURL + password (saucedemo defaults work out of the box)
npm test                      # full suite, green in ~under a minute

The AI-authoring workflow (the /from-issue etc. skills) additionally requires Claude Code, the Atlassian MCP connected, and gh authenticated. The tests themselves need none of that.

npm scripts

Project structure

.
├── src/
│   ├── pages/          # Page Objects (LoginPage, InventoryPage, CartPage, checkout/*)
│   ├── components/     # Reusable components (Header, Footer, CartBadge, BurgerMenu)
│   ├── fixtures/       # Playwright fixture — injects Page Objects into tests
│   ├── tcms/           # Qase TCMS mirror (seam, case-mapper, sync, client)
│   └── utils/          # env config (single process.env read point) + logger
├── data/               # Reference data (shared/products.json) + typed loaders (@data/*)
├── tests/              # Specs (one folder per feature) + auth.setup.ts + users.ts
├── auth/               # Generated storageState (git-ignored)
├── .claude/skills/     # AI authoring skills (from-issue, refine-ticket, scaffold-page-object, playwright-cli)
├── docs/               # architecture, app/, adr/, skill guides, tcms, superpowers/
└── .github/workflows/  # GitHub Actions CI

Configuration

All environment config flows through src/utils/env.ts (the single process.env read point). Copy .env.example → .env:

In CI these are GitHub Actions secrets.

Documentation