manoon-headless/src/__tests__/README.md

Manoon Storefront Test Suite

Comprehensive test suite for the ManoonOils storefront with focus on webhooks, commerce operations, and critical paths.

🎯 Coverage Goals

• Critical Paths: 80%+ coverage
• Webhook Handlers: 100% coverage
• Email Services: 90%+ coverage
• Analytics: 80%+ coverage

🧪 Test Structure

src/__tests__/
├── unit/
│   ├── services/           # Business logic tests
│   │   ├── OrderNotificationService.test.ts
│   │   └── AnalyticsService.test.ts
│   ├── stores/            # State management tests
│   │   └── saleorCheckoutStore.test.ts
│   └── utils/             # Utility function tests
│       └── formatPrice.test.ts
├── integration/
│   ├── api/
│   │   └── webhooks/
│   │       └── saleor.test.ts     # Webhook handler tests
│   └── emails/
│       ├── OrderConfirmation.test.tsx
│       └── OrderShipped.test.tsx
└── fixtures/              # Test data
    └── orders.ts

🚀 Running Tests

Unit & Integration Tests (Vitest)

# Run tests in watch mode
npm test

# Run tests once
npm run test:run

# Run with coverage report
npm run test:coverage

# Run with UI
npm run test:ui

E2E Tests (Playwright)

# Run all E2E tests
npm run test:e2e

# Run with UI mode
npm run test:e2e:ui

# Run specific test
npx playwright test tests/critical-paths/checkout-flow.spec.ts

📊 Test Categories

🔥 Critical Tests (Must Pass)

1. Webhook Handler Tests

   • ORDER_CONFIRMED: Sends emails + analytics
   • ORDER_CREATED: No duplicate emails/analytics
   • ORDER_FULFILLED: Tracking info included
   • ORDER_CANCELLED: Cancellation reason included
   • ORDER_FULLY_PAID: Payment confirmation

2. Email Service Tests

   • Correct translations (SR, EN, DE, FR)
   • Price formatting (no /100 bug)
   • Admin vs Customer templates
   • Address formatting

3. Analytics Tests

   • Revenue tracked once per order
   • Correct currency (RSD not USD)
   • Error handling (doesn't break order flow)

🔧 Integration Tests

• Full checkout flow
• Cart operations
• Email template rendering
• API error handling

🎭 Mocking Strategy

• Resend: Mocked (no actual emails sent)
• OpenPanel: Mocked (no actual tracking in tests)
• Saleor API: Can use real instance for integration tests (read-only)

📈 Coverage Reports

Coverage reports are generated in multiple formats:

• Console output (text)
• coverage/coverage-final.json (JSON)
• coverage/index.html (HTML report)

Open coverage/index.html in browser for detailed view.

🔍 Debugging Tests

# Debug specific test
npm test -- --reporter=verbose src/__tests__/unit/services/AnalyticsService.test.ts

# Debug with logs
DEBUG=true npm test

📝 Adding New Tests

1. Create test file: src/__tests__/unit|integration/path/to/file.test.ts
2. Import from @/ alias (configured in vitest.config.ts)
3. Use fixtures from src/__tests__/fixtures/
4. Mock external services
5. Run tests to verify

🚧 Current Limitations

• No CI/CD integration yet (informational only)
• E2E tests need Playwright browser installation
• Some tests use mocked data instead of real Saleor API

✅ Test Checklist

Before deploying, ensure:

• All webhook tests pass
• Email service tests pass
• Analytics tests pass
• Coverage >= 80% for critical paths
• No console errors in tests