Initial commit: add .gitignore and README
This commit is contained in:
defiQUG
286
tests/TESTING_GUIDE.md
Normal file
286
tests/TESTING_GUIDE.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user