ShopGuard

End-to-end test framework for e-commerce, built with Playwright + TypeScript. Cross-browser, mobile, visual, accessibility, and API coverage — wired to GitHub Actions and Allure.

Versão em português: README.pt-BR.md

---

Table of contents

• About
• Demo
• Tech stack
• Quick start
• Available commands
• Project structure
• Test reports
• CI/CD pipeline
• Roadmap
• Contributing
• Author

---

About

ShopGuard is a production-grade test automation framework for the SauceDemo e-commerce SUT. It demonstrates how a modern QA team would architect a Playwright suite that scales beyond the "happy-path script" stage:

• Page Object Model with composition (components like Header, ProductCard, ErrorContainer are injected, not duplicated)
• Custom fixtures that merge data generation, page objects, and a one-time login (storageState)
• Multi-project Playwright config (8 projects: setup, browser families, mobile viewports, API)
• Five flavors of testing in one repo: functional, mobile, visual regression, accessibility, and API
• Type-aware ESLint with eslint-plugin-playwright enforcing web-first assertions and banning waitForTimeout
• Husky + commitlint + lint-staged so broken code never lands in main
• Allure auto-published to GitHub Pages, fed by a 6-shard parallel matrix in GitHub Actions

This is project 1 of 4 in a QA Automation / SDET portfolio.

Demo

A 90-second walkthrough is being recorded. Until then, the Allure report shows the latest CI run with traces, videos, and screenshots.

   29 specs | 7 spec files | 5 browsers (chromium, firefox, webkit, Pixel 7, iPhone 14)
   API tests via JSONPlaceholder | Visual baselines | WCAG 2.1 AA audits

Tech stack

Layer	Choice	Why
Runner	Playwright ^1.59	Cross-browser native, auto-waiting, trace viewer, no flaky cy.wait legacy
Language	TypeScript ^5.7 (strict)	noUncheckedIndexedAccess, noImplicitOverride
Runtime	Node.js >=20 LTS	Long support, fully supported by Playwright
Test data	@faker-js/faker ^9	Domain-typed factories for Address, CreditCard, NewUser
Accessibility	@axe-core/playwright ^4.10	WCAG 2.1 AA audits
Reporting	Allure ^3 + Playwright HTML	Allure for CI + Pages, HTML for fast local debug
Quality gate	ESLint 9 flat config + Prettier 3 + Husky 9	Type-aware lint, web-first assertions enforced
CI/CD	GitHub Actions	Matrix sharding, browser cache, Pages deploy

Quick start

Prerequisites: Node.js 20 LTS (nvm use reads .nvmrc), npm 10+, Git, and ~500 MB free for browser binaries.

git clone https://github.com/JonnasFigueiredo/ShopGuard.git
cd ShopGuard
nvm use                        # picks Node 20 from .nvmrc (or install manually)
npm ci                         # exact reproduction of package-lock.json
cp .env.example .env           # SauceDemo creds are public, safe defaults
npx playwright install --with-deps
npm test                       # full suite, all projects

First run takes ~5–10 min (browser binaries download). Subsequent runs are seconds.

Run a single browser quickly

npm run test:chromium          # ~30s for the whole suite
npm run test:smoke             # only @smoke (~5s)
npm run test:ui                # Playwright UI mode for interactive debug

Available commands

Command	Description
npm test	Run every spec across every project
npm run test:smoke	Specs tagged @smoke only
npm run test:critical	Specs tagged @critical only
npm run test:regression	Specs tagged @regression only
npm run test:security	Specs tagged @security only
npm run test:chromium / :firefox / :webkit	Filter by desktop browser
npm run test:mobile	Pixel 7 (Chrome) + iPhone 14 (Safari)
npm run test:api	API tests (no browser)
npm run test:visual	Visual regression
npm run test:visual:update	Re-baseline visual snapshots
npm run test:a11y	Accessibility audits
npm run test:headed	Run with visible browser windows
npm run test:ui	Playwright UI mode
npm run test:debug	Step-debugger
npm run report	Open the last Playwright HTML report
npm run allure:serve	Generate + open Allure report locally
npm run lint / lint:fix	ESLint check / autofix
npm run format / format:check	Prettier write / verify
npm run typecheck	tsc --noEmit

Project structure

ShopGuard/
├── .github/workflows/         CI/CD pipelines (E2E Tests + Allure Report)
├── docs/                      Architecture decision records and strategy docs
│   ├── adr/                   Why Playwright, why POM, data strategy
│   ├── pt-BR/                 Portuguese mirrors of the docs
│   ├── TEST_STRATEGY.md
│   └── CONTRIBUTING.md
├── src/
│   ├── pages/                 Page Objects (BasePage + screen-specific)
│   │   └── components/        Reusable widgets (Header, Footer, ProductCard, ErrorContainer)
│   ├── fixtures/              Custom test/expect: data + page object + auth merging
│   ├── helpers/               Faker factories, API client, locator wrappers
│   ├── config/                Environment loader, routes, error copy, timeouts
│   └── types/                 Shared domain models
├── tests/
│   ├── auth.setup.ts          One-time login that persists .auth/user.json
│   ├── auth/                  Login flows (no storageState — fresh sessions)
│   ├── catalog/               Product listing + sorting
│   ├── checkout/              Cart and 3-step checkout flow
│   ├── api/                   Request-level tests (no browser overhead)
│   ├── visual/                Pixel-diff snapshots (chromium-only)
│   └── accessibility/         @axe-core/playwright audits (WCAG 2.1 AA)
├── playwright.config.ts       8 projects: setup, auth-*, browsers, mobile, api
├── tsconfig.json              strict + noUncheckedIndexedAccess + noImplicitOverride
├── eslint.config.js           Flat config, type-aware, eslint-plugin-playwright
└── .nvmrc                     Node 20 LTS

Test reports

• Latest CI run: Allure on GitHub Pages — auto-deployed after every push to main
• Local Playwright HTML: npm run report after a test run
• Local Allure: npm run allure:serve
• Failed-test artifacts: traces, videos, and screenshots are uploaded by the workflow under traces-* (failure-only retention 7 days)

CI/CD pipeline

Two GitHub Actions workflows, kept intentionally separate so report publication does not block test execution:

e2e-tests.yml

• Triggers: push to main, pull requests targeting main, nightly cron at 03:00 UTC, manual dispatch
• Concurrency: cancels in-flight PR runs on new commits; preserves main runs for history
• Jobs:
  • lint-and-typecheck — fast quality gate (~30s) that bails before browser jobs
  • browser-tests — 3×2 matrix (chromium / firefox / webkit family × 2 shards = 6 parallel runners)
  • api-tests — standalone, no browser
• Caching: npm + ~/.cache/ms-playwright. On cache hit, only system deps are reinstalled
• Artifacts: Playwright HTML report, Allure results (always); traces (failure only, 7-day retention)

allure-report.yml

• Trigger: runs after e2e-tests.yml completes on main
• Pulls every shard's allure-results-* artifact, merges them, generates the report
• Deploys to GitHub Pages via actions/deploy-pages@v4

Roadmap

• 90-second demo GIF in this README
• Allure trend graphs (requires history persistence between runs)
• Visual-diff comments on PRs (post-screenshot diffs as PR comments)
• Mutation testing with Stryker on Page Objects
• Contract testing with Pact against a real API
• Coverage of problem_user and performance_glitch_user edge cases
• Per-environment test data factories (dev / staging / prod)
• Slack / Discord notification on main failure

Contributing

See docs/CONTRIBUTING.md for the full contribution guide. TL;DR:

git checkout -b feat/your-change
# ... make changes; husky runs lint-staged + commitlint on commit
git commit -m "feat(scope): short description"
git push -u origin feat/your-change
gh pr create

All PRs go through the GitHub Actions matrix above. Merge is blocked until lint, typecheck, and the full suite pass.

Author

Jonnas Figueiredo — QA Engineer building toward QA Automation / SDET roles.

• GitHub: @JonnasFigueiredo
• LinkedIn: jonnas-figueiredo
• Email: jonnasrock@gmail.com

This project is part of a 4-piece QA portfolio. Released under the MIT License.