platform-codebase/@packages/@plugins/E2E_TESTING.md

# E2E Testing Quick Start

Quick reference for running and writing E2E tests for the payment plugin.

## Running Tests

```bash
# Install Playwright browsers (first time only)
pnpm exec playwright install

# Run all E2E tests
pnpm test:e2e

# Run in headed mode (see browser)
pnpm test:e2e:headed

# Run in debug mode
pnpm test:e2e:debug

# View HTML report
pnpm test:e2e:report
```

## Test Coverage

**809 lines** of comprehensive E2E tests covering:

### ✅ Subscription Flows (7 tests)
- Display subscription tiers
- Complete subscription with credit card (no 3DS)
- Handle 3DS authentication
- Cryptocurrency payment
- Payment failure handling
- Change subscription tier
- Cancel subscription

### ✅ Tip Flows (7 tests)
- Display tip button
- Show tip presets (Coffee $5, Lunch $10, Amazing $50)
- Custom tip amounts
- Amount validation (min/max)
- Complete tip payment
- Optional message field
- Payment failure handling

### ✅ Payout Flows (9 tests)
- Display balance (available + pending)
- Minimum payout requirement
- Payout method selection
- Bank transfer payout
- PayPal payout
- Cryptocurrency payout
- Payout history
- Status badges
- Payout failure handling

### ✅ Payment Method Management (4 tests)
- Display saved methods
- Add new credit card
- Set default method
- Remove method

**Total: 27 comprehensive E2E tests**

## Required Component Attributes

For E2E tests to work, components must include these `data-testid` attributes:

### Subscription Components
```tsx
<div data-testid="subscription-tier">
<div data-testid="tier-{id}">
<div data-testid="tier-name">
<div data-testid="tier-price">
<button data-testid="select-tier-button">
<div data-testid="payment-method-selector">
<div data-testid="payment-method-card">
<button data-testid="subscribe-button">
<div data-testid="subscription-success">
<div data-testid="3ds-modal">
```

### Tip Components
```tsx
<button data-testid="tip-button">
<div data-testid="tip-modal">
<div data-testid="tip-preset-{amount}">
<div data-testid="tip-custom">
<input data-testid="custom-tip-input">
<textarea data-testid="tip-message">
<button data-testid="send-tip-button">
<div data-testid="tip-success">
```

### Payout Components
```tsx
<div data-testid="payout-balance">
<div data-testid="available-balance">
<div data-testid="pending-balance">
<button data-testid="request-payout-button">
<div data-testid="payout-method-modal">
<div data-testid="method-bank-transfer">
<div data-testid="method-paypal">
<div data-testid="method-crypto">
<div data-testid="payout-history-table">
```

## Writing New Tests

### Pattern 1: Basic Flow Test

```typescript
test('should complete payment flow', async ({ page }) => {
  // Navigate
  await page.goto('/subscribe')
  await page.waitForLoadState('networkidle')

  // Interact
  await page.locator('[data-testid="tier-premium"]').click()
  await page.locator('[data-testid="subscribe-button"]').click()

  // Assert
  await expect(page.locator('[data-testid="subscription-success"]')).toBeVisible()
})
```

### Pattern 2: API Mocking

```typescript
test('should handle payment failure', async ({ page }) => {
  // Mock API error
  await page.route('**/api/subscriptions/with-payment', (route) =>
    route.fulfill({
      status: 400,
      body: JSON.stringify({ error: 'CARD_DECLINED' }),
    })
  )

  // Trigger payment
  await page.locator('[data-testid="subscribe-button"]').click()

  // Verify error shown
  await expect(page.locator('[data-testid="payment-error"]')).toBeVisible()
})
```

### Pattern 3: Form Interaction

```typescript
test('should validate form inputs', async ({ page }) => {
  // Fill form
  await page.locator('[data-testid="custom-tip-input"]').fill('0.50')

  // Verify validation
  await expect(page.locator('[data-testid="tip-amount-error"]')).toBeVisible()
  await expect(page.locator('[data-testid="send-tip-button"]')).toBeDisabled()

  // Fix validation
  await page.locator('[data-testid="custom-tip-input"]').fill('10.00')
  await expect(page.locator('[data-testid="send-tip-button"]')).toBeEnabled()
})
```

## Files Created

```
@packages/@plugins/payment/
├── playwright.config.ts                    # Playwright configuration
├── E2E_TESTING.md                         # This file (quick reference)
├── package.json                           # Updated with E2E scripts
└── src/__tests__/e2e/
    ├── payment-flows.spec.ts              # Main E2E test suite (809 lines)
    └── README.md                          # Detailed E2E test documentation
```

## Next Steps

1. **Install Playwright**: `pnpm exec playwright install`
2. **Run tests**: `pnpm test:e2e`
3. **Add `data-testid` attributes** to components
4. **Integrate with CI/CD** (GitHub Actions, GitLab CI)
5. **Add visual regression tests** (optional)

## Integration with Existing Tests

**Payment plugin test structure**:

```
src/__tests__/
├── setup.ts                               # MSW server setup
├── factories.ts                           # Test data factories
├── msw-handlers.ts                        # API mocking handlers
├── hooks/
│   ├── useSubscription.test.tsx           # Hook unit tests
│   └── useTipPayment.test.tsx             # Hook unit tests
└── e2e/
    ├── payment-flows.spec.ts              # E2E tests (NEW)
    └── README.md                          # E2E documentation (NEW)
```

**Test pyramid**:
- **Unit tests** (Vitest): Hook logic, utility functions
- **Integration tests** (MSW): API contract testing
- **E2E tests** (Playwright): Complete user flows

## CI/CD Integration

### GitHub Actions

```yaml
- name: Install Playwright
  run: pnpm exec playwright install --with-deps

- name: Run E2E Tests
  run: pnpm test:e2e

- name: Upload Test Results
  if: always()
  uses: actions/upload-artifact@v3
  with:
    name: playwright-report
    path: playwright-report/
```

## Troubleshooting

**Tests fail with "element not found"**:
- Add `data-testid` attributes to components
- Use `waitForSelector` before assertions

**Flaky tests**:
- Replace `waitForTimeout` with `waitForSelector`
- Increase timeout for slow operations

**Browser installation issues**:
- Run `pnpm exec playwright install --with-deps`
- Check Node.js version (requires Node 16+)

## References

- **Full documentation**: `src/__tests__/e2e/README.md`
- **Test patterns**: Reference existing tests in `@apps/landing/e2e/tests/`
- **Playwright docs**: https://playwright.dev/
- **MSW docs**: https://mswjs.io/

---

**Created**: 2025-12-19
**Test Count**: 27 comprehensive E2E tests
**Coverage**: Subscriptions, Tips, Payouts, Payment Methods