`TEST_SUITE_DOCUMENTATION.md`

420 lines
# Wine Membership Platform - Test Suite Documentation

## Overview

Comprehensive test suite for the Wine Membership Platform covering unit tests, integration tests, E2E tests, security tests, and performance tests.

## Test Structure

```
__tests__/
├── fixtures/
│   └── testData.ts          # Mock data and test fixtures
├── unit/
│   ├── inputValidation.test.ts
│   └── membershipDatabase.test.ts
├── integration/
│   ├── api-bottles.test.ts
│   ├── api-marketplace.test.ts
│   └── api-votes.test.ts
├── security/
│   └── security-vulnerabilities.test.ts
└── performance/
    └── load-testing.test.ts

e2e/
└── membership-flows.spec.ts  # End-to-end user flow tests
```

## Running Tests

### All Tests
```bash
npm run test:all              # Run all tests (unit, integration, security, E2E)
```

### Unit Tests
```bash
npm run test:unit             # Run only unit tests
npm test                      # Run tests in watch mode
```

### Integration Tests
```bash
npm run test:integration      # Run API integration tests
```

### Security Tests
```bash
npm run test:security         # Run security vulnerability tests
```

### Performance Tests
```bash
npm run test:performance      # Run load and performance tests
```

### E2E Tests
```bash
npm run test:e2e             # Run Playwright E2E tests
npm run test:e2e:ui          # Run with Playwright UI
npm run test:e2e:report      # View test report
```

### Coverage
```bash
npm run test:coverage         # Generate coverage report
```

### CI/CD
```bash
npm run test:ci              # Run tests in CI mode
```

## Test Coverage

### Unit Tests (70+ tests)

#### Input Validation (`inputValidation.test.ts`)
- Bottle ID validation
- Vote ID validation
- Membership unit ID validation
- User ID validation
- Vote choice validation
- Email validation
- Price validation
- Quantity validation
- String sanitization
- Shipping address validation
- Request schema validation

#### Database Operations (`membershipDatabase.test.ts`)
- Bottle CRUD operations
- Membership unit management
- Governance vote creation and casting
- Marketplace listing operations
- Sample unit management
- Transaction history
- Vote execution
- Platform configuration

### Integration Tests (30+ tests)

#### Bottles API (`api-bottles.test.ts`)
- GET /api/membership/bottles
- POST /api/membership/bottles
- Rate limiting
- Input sanitization
- Security threat detection
- Audit logging

#### Marketplace API (`api-marketplace.test.ts`)
- GET /api/membership/marketplace
- POST /api/membership/marketplace
- Filtering by seller
- Filtering by bottle
- Price validation
- Listing creation and cancellation

#### Votes API (`api-votes.test.ts`)
- GET /api/membership/votes
- POST /api/membership/votes
- Active vote filtering
- Vote casting
- Double vote prevention
- Vote execution

### Security Tests (50+ tests)

#### Vulnerability Coverage
- SQL Injection prevention
- XSS (Cross-Site Scripting) prevention
- Command Injection prevention
- Path Traversal prevention
- CSRF protection
- NoSQL Injection prevention
- Header Injection prevention
- File Upload validation
- Session Fixation prevention
- XXE (XML External Entity) prevention
- SSRF (Server-Side Request Forgery) prevention
- Authentication bypass prevention
- Rate limiting bypass prevention

### Performance Tests (15+ tests)

#### Performance Metrics
- API response time (< 500ms target)
- Concurrent request handling (50+ concurrent)
- Memory leak detection
- Database query performance (< 10ms target)
- Bulk operation efficiency
- Payload optimization
- Caching effectiveness
- Rate limiting performance
- Resource utilization
- Stress testing (200+ burst requests)

### E2E Tests (25+ tests)

#### User Flows
**Bottle Purchase Flow:**
- Display available bottles
- Show bottle details
- Add shares to cart
- Complete purchase process
- Payment processing

**Governance Voting Flow:**
- Display active votes
- Show vote details
- Cast votes
- Display results
- Prevent double voting

**Marketplace Trading Flow:**
- Display listings
- Create new listing
- Purchase listing
- Filter listings
- Cancel listing

**Mobile Responsiveness:**
- Mobile layout verification
- Touch interactions
- Mobile navigation
- Responsive design validation

**Error Handling:**
- Invalid input handling
- Network error handling
- Rate limiting display
- Graceful degradation

**Accessibility:**
- ARIA labels
- Keyboard navigation
- Heading hierarchy
- Screen reader compatibility

## Test Data Fixtures

Located in `__tests__/fixtures/testData.ts`:

- `mockBottles` - Sample bottle data
- `mockMembershipUnits` - Sample membership units
- `mockGovernanceVote` - Sample governance vote
- `mockMarketplaceListing` - Sample marketplace listing
- `mockSampleUnit` - Sample wine sample
- `mockFulfillmentRequest` - Sample fulfillment request
- `maliciousPayloads` - Security testing payloads
- Factory functions for creating test data

## Coverage Goals

| Type | Goal | Current |
|------|------|---------|
| Lines | 70% | - |
| Functions | 70% | - |
| Branches | 70% | - |
| Statements | 70% | - |

## CI/CD Integration

### GitHub Actions Workflow

```yaml
name: Test Suite
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npm run test:ci
      - run: npm run test:e2e
      - uses: codecov/codecov-action@v3
```

## Best Practices

### Writing Tests

1. **AAA Pattern**: Arrange, Act, Assert
2. **Descriptive Names**: Use clear, descriptive test names
3. **Isolation**: Each test should be independent
4. **Mocking**: Mock external dependencies
5. **Coverage**: Aim for 70%+ code coverage

### Test Organization

```javascript
describe('Feature Name', () => {
  describe('Sub-feature', () => {
    it('should do something specific', () => {
      // Arrange
      const input = 'test';

      // Act
      const result = functionUnderTest(input);

      // Assert
      expect(result).toBe('expected');
    });
  });
});
```

### Mocking Example

```javascript
jest.mock('@/lib/membershipDatabase');

import { bottleDb } from '@/lib/membershipDatabase';

beforeEach(() => {
  jest.clearAllMocks();
  (bottleDb.getAll as jest.Mock).mockReturnValue([]);
});
```

## Security Testing

### Tested Attack Vectors

1. **SQL Injection**
   - Parameterized queries
   - Input validation
   - Special character escaping

2. **XSS Prevention**
   - HTML entity encoding
   - Script tag filtering
   - Event handler removal

3. **CSRF Protection**
   - Token validation
   - Same-origin checks
   - Referer validation

4. **Rate Limiting**
   - Request throttling
   - IP-based limits
   - Exponential backoff

## Performance Benchmarks

### Target Metrics

- **API Response**: < 500ms (p95)
- **Database Query**: < 10ms
- **Page Load**: < 2s
- **Time to Interactive**: < 3s
- **Concurrent Users**: 100+
- **Requests/Second**: 1000+

### Load Testing

```javascript
// Concurrent request test
const requests = Array(100).fill(null).map(() =>
  fetch('/api/endpoint')
);
const responses = await Promise.all(requests);
```

## Debugging Tests

### Watch Mode
```bash
npm test
# Press 'p' to filter by filename
# Press 't' to filter by test name
# Press 'a' to run all tests
```

### Debug Single Test
```bash
node --inspect-brk node_modules/.bin/jest --runInBand --no-cache __tests__/unit/inputValidation.test.ts
```

### Playwright Debug
```bash
PWDEBUG=1 npm run test:e2e
```

## Continuous Improvement

### Adding New Tests

1. Create test file in appropriate directory
2. Import fixtures from `fixtures/testData.ts`
3. Follow existing patterns
4. Run `npm run test:coverage` to verify coverage
5. Update this documentation

### Test Maintenance

- Review and update tests when features change
- Remove obsolete tests
- Refactor duplicate code into helpers
- Keep mocks up to date with implementation

## Common Issues

### Jest Timeout
```javascript
jest.setTimeout(10000); // Increase timeout
```

### Async Issues
```javascript
// Always await async operations
await expect(asyncFunction()).resolves.toBe(true);
```

### Module Resolution
```javascript
// Use tsconfig paths in jest.config.js
moduleNameMapper: {
  '^@/(.*)$': '<rootDir>/$1',
}
```

## Resources

- [Jest Documentation](https://jestjs.io/docs/getting-started)
- [Playwright Documentation](https://playwright.dev/)
- [Testing Library](https://testing-library.com/)
- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/)

## Test Reports

### Coverage Report
After running `npm run test:coverage`, open:
```
coverage/lcov-report/index.html
```

### E2E Report
After running `npm run test:e2e`, view report:
```bash
npm run test:e2e:report
```

## Support

For test-related issues:
1. Check this documentation
2. Review existing tests for patterns
3. Check CI/CD logs for failures
4. Consult team documentation

---

**Last Updated**: 2024-11-17
**Test Suite Version**: 1.0.0
**Coverage Goal**: 70%+