SauceDemo Playwright Educational Framework

This repository is a focused educational Playwright project for prospective QA Automation engineers.

It demonstrates:

• basic Playwright test authoring
• Page Object Model structure
• centralized locator management
• cross-browser execution in Chrome and Edge
• modern Playwright tooling paths for agents, MCP, UI mode, and codegen

Tech Stack

• Node.js >=18.0.0
• Playwright 1.61.1 (@playwright/test), with roadmap guidance aligned to the Playwright 1.60 agentic feature set
• ESM modules ("type": "module")

Cross-Platform Setup (Windows, macOS, Linux)

Use this section if you are starting from a machine with no prior project setup.

1) Install Prerequisites

You need:

• Git
• Node.js >=18
• npm (included with Node.js)

Windows:

• Install Node.js LTS from nodejs.org
• Install Git from git-scm.com

macOS (Homebrew):

brew install node git
xcode-select --install

Linux (Debian/Ubuntu example):

sudo apt-get update
sudo apt-get install -y nodejs npm git

Verify:

node -v
npm -v
git --version

2) Clone the Repository

git clone <your-repo-url>
cd SauceDemo-Playwright

Project Layout

• tests/ - automated tests
• pages/ - page object classes
• locators/ - shared selectors
• playwright.config.ts - test runner config

Getting Started

1. Install dependencies:

npm install

2. Install browsers:

npm run install:browsers

Linux users should prefer installing OS dependencies together with browser setup:

npx playwright install --with-deps

3. Create a local .env file with SauceDemo credentials:

LOGIN_USERNAME=standard_user
LOGIN_PASSWORD=secret_sauce

You can copy .env.template and update values.

Run Tests

• Run all tests:

npm test

• Run headed mode:

npm run test:headed

• Run Chrome only:

npm run test:chrome

• Run Edge only:

npm run test:edge

• Run Playwright UI mode:

npm run test:ui

• Run Playwright debug mode:

npm run test:debug

• Refresh snapshot assertions:

npm run test:update-snapshots

• Run ARIA snapshot educational suite only:

npm run test:aria

• Refresh ARIA snapshot suite baselines:

npm run test:aria:update

• Initialize Playwright test agents for VS Code workflows:

npm run agents:init

• Launch the Playwright MCP server:

npm run mcp:server

• Launch Playwright codegen against SauceDemo:

npm run codegen:saucedemo

• Open HTML report:

npm run report

Recommended First Run

For a clean SauceDemo health check (excluding procedural demo):

npx playwright test tests/saucedemo

Learning Flow

1. Start in tests/procedural_demo/ for direct Playwright syntax.
2. Move to tests/saucedemo/ for fixture + page-object usage.
3. Trace selectors in locators/ and actions in pages/.
4. Introduce tests/aria-snapshots/ only after students are comfortable writing manual tests.

Coverage Snapshot

Currently implemented SauceDemo scenarios:

• login
• inventory title verification
• add to cart
• remove from cart
• open cart
• checkout completion

Current gaps (recommended next additions):

• invalid login behavior
• logout flow
• cart badge count validation
• product sorting behavior
• checkout validation errors (missing first name/last name/postal code)
• cancel-from-checkout flow assertions

See detailed analysis in docs/testing/TESTCOVERAGEGAPS.md.

After any Playwright version bump, refresh browser binaries before running the suite. The 1.60 release guidance calls this out explicitly, and it remains a good rule on later releases.

Modernization Roadmap

The next expansion areas are tracked in priority order in docs/testing/PLAYWRIGHT-MODERNIZATION-ROADMAP.md:

1. Test Agents (planner, generator, and healer)
2. Playwright MCP Server
3. Aria Snapshot Assertion based testing
4. WebAuthn passkeys
5. Codegen demonstration
6. Screencast API and UI mode

Documentation

• docs/PROJECT-OVERVIEW.md
• docs/setup/PROJECTSETUPLOCAL.md
• docs/setup/PROJECTSTRUCTURE.md
• docs/testing/TESTRUNNING.md
• docs/testing/TESTRESULTS.md
• docs/testing/TESTDEBUGERRORS.md
• docs/testing/TESTCREATEMOD.md
• docs/testing/TESTCOVERAGEGAPS.md
• docs/testing/PLAYWRIGHT-AGENT-FINDINGS.md
• docs/testing/PLAYWRIGHT-ARIA-SNAPSHOTS-GUIDE.md
• docs/testing/PLAYWRIGHT-TEST-AGENTS-MCP.md
• docs/testing/PLAYWRIGHT-MCP-SMOKE-FLOW.md
• docs/testing/PLAYWRIGHT-MODERNIZATION-ROADMAP.md