dbis_core-lite/tests/TESTING_GUIDE.md

# Testing Guide - DBIS Core Lite

## Overview

This document describes the comprehensive test suite for the DBIS Core Lite payment processing system. The test suite ensures functionality, compliance, and security requirements are met.

## Test Structure

```
tests/
├── unit/                    # Unit tests for individual components
│   ├── repositories/        # Repository layer tests
│   ├── services/           # Service layer tests
│   └── ...
├── integration/            # Integration tests for API endpoints
├── compliance/             # Compliance and regulatory tests
│   ├── screening/          # Sanctions/PEP screening
│   └── dual-control/       # Maker/Checker enforcement
├── security/               # Security tests
│   ├── authentication/     # Auth and JWT tests
│   └── rbac/              # Role-based access control
├── validation/             # Input validation tests
├── e2e/                    # End-to-end workflow tests
└── utils/                  # Test utilities and helpers
```

## Test Categories

### 1. Unit Tests

#### Repositories (`tests/unit/repositories/`)
- **PaymentRepository** - CRUD operations, idempotency, status updates
- **MessageRepository** - ISO message storage and retrieval
- **OperatorRepository** - Operator management
- **SettlementRepository** - Settlement tracking

#### Services (`tests/unit/services/`)
- **MessageService** - ISO 20022 message generation and validation
- **TransportService** - TLS message transmission
- **LedgerService** - Account posting and fund reservation
- **ScreeningService** - Compliance screening

### 2. Compliance Tests (`tests/compliance/`)

#### Screening Tests
- Sanctions list checking
- PEP (Politically Exposed Person) screening
- BIC sanctions validation
- Screening result storage and retrieval

#### Dual Control Tests
- Maker/Checker separation enforcement
- Role-based approval permissions
- Payment status validation
- Same-operator prevention

### 3. Security Tests (`tests/security/`)

#### Authentication Tests
- Credential verification
- JWT token generation and validation
- Password hashing
- Token expiration handling

#### RBAC Tests
- Role-based endpoint access
- MAKER role restrictions
- CHECKER role restrictions
- ADMIN role privileges
- Dual control enforcement

### 4. Validation Tests (`tests/validation/`)

#### Payment Validation
- Required field validation
- Amount validation (positive, precision)
- Currency validation
- BIC format validation (BIC8/BIC11)
- Account format validation
- Optional field handling

### 5. Integration Tests (`tests/integration/`)

#### API Endpoint Tests
- Authentication endpoints
- Payment workflow endpoints
- Operator management endpoints
- Error handling
- Request validation

### 6. E2E Tests (`tests/e2e/`)

#### Payment Flow Tests
- Complete payment lifecycle
- Maker initiation → Checker approval → Processing
- Compliance screening → Ledger posting → Message generation
- Transmission → ACK → Settlement

## Running Tests

### Run All Tests
```bash
npm test
```

### Run Specific Test Suite
```bash
npm test -- tests/unit/repositories
npm test -- tests/compliance
npm test -- tests/security
```

### Run with Coverage
```bash
npm run test:coverage
```

### Run in Watch Mode
```bash
npm run test:watch
```

### Run Single Test File
```bash
npm test -- payment-repository.test.ts
```

## Test Environment Setup

### Prerequisites
1. PostgreSQL test database
2. Test database URL: `TEST_DATABASE_URL` environment variable
3. Default: `postgresql://postgres:postgres@localhost:5432/dbis_core_test`

### Test Database Setup
```bash
# Create test database
createdb dbis_core_test

# Run migrations on test database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/dbis_core_test npm run migrate
```

### Environment Variables
```bash
NODE_ENV=test
JWT_SECRET=test-secret-key-for-testing-only
TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/dbis_core_test
```

## Test Utilities

### TestHelpers Class
Located in `tests/utils/test-helpers.ts`:

- `getTestDb()` - Get test database connection
- `cleanDatabase()` - Truncate test tables
- `createTestOperator()` - Create test operator with specified role
- `generateTestToken()` - Generate JWT token for testing
- `createTestPaymentRequest()` - Create valid payment request object
- `sleep()` - Utility for async test delays

## Test Coverage Goals

### Current Coverage Targets
- **Unit Tests**: >80% coverage
- **Integration Tests**: >70% coverage
- **Critical Paths**: 100% coverage
  - Payment workflow
  - Compliance screening
  - Authentication/Authorization
  - Message generation
  - Ledger operations

### Critical Components Requiring 100% Coverage
1. Payment workflow orchestration
2. Compliance screening engine
3. Authentication and authorization
4. Dual control enforcement
5. ISO 20022 message generation
6. Audit logging

## Compliance Testing Requirements

### Regulatory Compliance
- **Sanctions Screening**: Must test OFAC, EU, UK sanctions lists
- **PEP Screening**: Must test PEP database queries
- **Dual Control**: Must enforce Maker/Checker separation
- **Audit Trail**: Must log all payment events
- **Data Integrity**: Must validate all payment data

### Banking Standards
- **ISO 20022 Compliance**: Message format validation
- **BIC Validation**: Format and checksum validation
- **Transaction Limits**: Amount and frequency limits
- **Settlement Finality**: Credit confirmation tracking

## Security Testing Requirements

### Authentication
- ✅ Password hashing (bcrypt)
- ✅ JWT token generation and validation
- ✅ Token expiration
- ✅ Credential verification

### Authorization
- ✅ RBAC enforcement
- ✅ Role-based endpoint access
- ✅ Dual control separation
- ✅ Permission validation

### Input Validation
- ✅ SQL injection prevention
- ✅ XSS prevention
- ✅ Input sanitization
- ✅ Schema validation

## Continuous Integration

### CI/CD Integration
Tests should run automatically on:
- Pull requests
- Commits to main/master
- Pre-deployment checks

### Test Execution in CI
```yaml
# Example GitHub Actions
- name: Run Tests
  run: |
    npm test
    npm run test:coverage
```

## Test Data Management

### Test Data Isolation
- Each test suite cleans up after itself
- Tests use unique identifiers to avoid conflicts
- Database truncation between test runs

### Test Operators
- Created with predictable IDs for consistency
- Roles: MAKER, CHECKER, ADMIN
- Password: Standard test password (configurable)

## Best Practices

1. **Test Isolation**: Each test should be independent
2. **Clean State**: Clean database before/after tests
3. **Mocking**: Mock external services (ledger, TLS)
4. **Assertions**: Use descriptive assertions
5. **Test Names**: Clear, descriptive test names
6. **Coverage**: Aim for high coverage but focus on critical paths

## Troubleshooting

### Common Issues

1. **Database Connection Errors**
   - Verify TEST_DATABASE_URL is set
   - Check PostgreSQL is running
   - Verify database exists

2. **Test Timeouts**
   - Increase Jest timeout for slow tests
   - Check for hanging database connections

3. **Fixture Data Issues**
   - Ensure database is cleaned between tests
   - Use unique identifiers for test data

## Next Steps

- [ ] Add service layer unit tests
- [ ] Enhance E2E tests with real workflow scenarios
- [ ] Add performance/load tests
- [ ] Add contract tests for external integrations
- [ ] Add chaos engineering tests for resilience

---

**Last Updated**: 2025-12-28
**Test Framework**: Jest
**Coverage Tool**: Jest Coverage