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

npm test

Run Specific Test Suite

npm test -- tests/unit/repositories
npm test -- tests/compliance
npm test -- tests/security

Run with Coverage

npm run test:coverage

Run in Watch Mode

npm run test:watch

Run Single Test File

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

# 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

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

# 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