/supergraph:playwright-tester

Complete Web QA/QC & Playwright E2E testing framework. From business requirement analysis to resilient test automation and defect reporting.

Announce: "🎭 /supergraph:playwright-tester — designing QA matrix & automating Playwright E2E tests..."

---

When to Use

• Writing comprehensive E2E tests for web applications (Next.js, Vite, React, Vue, Angular, SSR/SPA)
• Testing complete business flows (happy path, validation failures, boundary states)
• Simulating system failures: API down (500), network timeout, offline mode, rate limit (429)
• Testing Authentication & Authorization (RBAC, unauthenticated redirects, expired token)
• Creating Page Object Model (POM) test architecture from scratch
• Performing formal QA/QC regression testing and generating defect reports

---

The 4-Phase QA/QC Workflow

[Phase 1: QA Analyst]        [Phase 2: SDET]           [Phase 3: Runner]        [Phase 4: QC Lead]
Business Test Matrix  ───>  Playwright Automation ───>  Execution & Tracing ───> Defect Report & Gate
(Happy/Sad/Boundary/        (POM, Resilient Selectors,  (Trace, Screenshots,    (Blocker/Major,
 Network Failure/RBAC)       page.route API mocks)       Console & Network Logs) Steps to Reproduce)

---

Phase 1: Business Test Matrix (QA Analyst)

Before writing any automation code, map out the test matrix using Given-When-Then format across 5 core test dimensions:

1. Happy Path (Primary Business Flow)

• Complete user journey from start to desired outcome with valid inputs.
• Verification of UI state changes, persistence, and navigation.

2. Negative Path (Sad Path & Validation)

• Missing required fields, invalid email/phone, password rules.
• Invalid business logic: expired coupon, insufficient balance, duplicate registration.
• Verify exact user-facing error messages, field highlight, and form submission prevention.

3. Boundary & Edge Cases

• Min/Max input limits (0, 1, max chars, special unicode/HTML characters).
• Rapid duplicate clicks (double-submit prevention on payment or submission buttons).
• Empty states (empty shopping cart, no search results, initial empty dashboard).

4. Authentication & RBAC (Role-Based Access Control)

• Unauthenticated user hitting protected routes → redirect to /login with returnUrl.
• Role isolation: User trying to access /admin → 403 Forbidden or redirected.
• Session expiration during an active workflow.

5. Network & System Resilience (Fault Injection)

• Backend failure: Mock 500 Internal Server Error on critical API calls → verify graceful toast/banner error, no white screen.
• Slow network / Latency: Mock 3000ms delay → verify loading skeletons/spinners and disabled submit buttons.
• Offline behavior: Disconnect network → verify offline indicators.

---

Phase 2: Playwright Automation Engine (SDET)

Rule 1: Resilient User-Centric Selectors (Strict Priority)

Never use fragile CSS classes (.btn-primary.mt-4) or positional XPath (//div[2]/button[1]).

Priority	Selector Method	Example
1 (Best)	page.getByRole()	page.getByRole('button', { name: 'Submit Order' })
2	page.getByLabel()	page.getByLabel('Email address')
3	page.getByPlaceholder()	page.getByPlaceholder('Enter your password')
4	page.getByText()	page.getByText('Order completed successfully')
5	page.getByTestId()	page.getByTestId('order-summary-card')

Rule 2: Page Object Model (POM) Structure

Encapsulate page locators and user interactions into reusable page classes:

// tests/pages/checkout.page.ts
import { type Page, type Locator, expect } from '@playwright/test';

export class CheckoutPage {
  readonly page: Page;
  readonly cardInput: Locator;
  readonly payButton: Locator;
  readonly errorAlert: Locator;

  constructor(page: Page) {
    this.page = page;
    this.cardInput = page.getByLabel('Card Number');
    this.payButton = page.getByRole('button', { name: 'Pay Now' });
    this.errorAlert = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/checkout');
    await expect(this.payButton).toBeVisible();
  }

  async submitPayment(cardNumber: string) {
    await this.cardInput.fill(cardNumber);
    await this.payButton.click();
  }
}

Rule 3: Session & Auth Optimization (storageState)

Never log in through the UI on every test. Authenticate once in a setup project and save state:

// playwright.config.ts
export default defineConfig({
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'e2e-authenticated',
      dependencies: ['setup'],
      use: { storageState: 'playwright/.auth/user.json' },
    },
    {
      name: 'e2e-anonymous',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

Rule 4: Network Interception & Failure Injection (page.route)

Simulate backend failures deterministically without touching test DB:

// Simulating API 500 Error
test('displays error notification when order submission fails', async ({ page }) => {
  await page.route('**/api/v1/orders', async route => {
    await route.fulfill({
      status: 500,
      contentType: 'application/json',
      body: JSON.stringify({ message: 'Database connection failed' }),
    });
  });

  const checkoutPage = new CheckoutPage(page);
  await checkoutPage.goto();
  await checkoutPage.submitPayment('4242424242424242');

  await expect(checkoutPage.errorAlert).toBeVisible();
  await expect(checkoutPage.errorAlert).toContainText('Database connection failed');
});

Rule 5: Auto-Waiting Assertions (Zero Arbitrary Sleeps)

• FORBIDDEN: await page.waitForTimeout(3000) (causes flakiness or slow tests).
• MANDATORY: Web-first auto-retrying assertions:
  • await expect(locator).toBeVisible()
  • await expect(locator).toHaveText('...')
  • await expect(locator).toBeEnabled()
  • await expect(page).toHaveURL(/.*checkout/)

---

Phase 3: Execution, Flakiness Guard & Artifacts

Run test execution with tracing enabled for failure post-mortem:

# Run all tests
npx playwright test

# Run single file with UI / trace
npx playwright test tests/e2e/checkout.spec.ts --trace on

# Run headed for visual debugging
npx playwright test --headed

Configuration essentials in playwright.config.ts:

• trace: 'retain-on-failure'
• screenshot: 'only-on-failure'
• video: 'retain-on-failure'
• webServer: auto-start dev server if not already running.

---

Phase 4: QC Defect & Quality Gate Report

When any test fails during execution, format the defect report immediately:

### 🐛 QA Defect Report

- **Defect ID**: BUG-001
- **Severity**: Blocker | Critical | Major | Minor
- **Affected Flow**: [e.g. Checkout → Payment Submission]
- **Environment**: Chromium / Mobile Safari / Desktop

#### 1. Steps to Reproduce
1. Navigate to `/checkout` with 1 item in cart
2. Enter invalid card number `1234`
3. Click "Pay Now"

#### 2. Expected Result
- Button disabled or error message "Invalid card number" appears below input.
- No network request sent with invalid card format.

#### 3. Actual Result
- Error message missing. Unhandled promise rejection in browser console.
- Blank white screen rendered.

#### 4. Evidence & Artifacts
- Screenshot: `test-results/checkout-failure.png`
- Trace Viewer: `npx playwright show-trace test-results/trace.zip`
- Console Error: `TypeError: Cannot read properties of undefined (reading 'status')`

#### 5. Root Cause Hypothesis
- `useCheckout.ts:84` does not handle rejected promise from `api.submit()`.

---

Execution Checklist

• Business test matrix defined (Happy, Sad, Boundary, RBAC, Network Failure)
• Selectors follow role/label/testId priority (no raw CSS/XPath)
• POM pattern applied for multi-step or shared pages
• Backend error states simulated via page.route
• Auto-waiting assertions used exclusively (no waitForTimeout)
• Artifacts captured (Trace, screenshots, video on failure)
• Quality gate report produced with clear PASS/FAIL verdict