xpeditis2.0/apps/backend/test/integration

Integration Tests

This directory contains integration tests for the Xpeditis backend infrastructure layer.

Overview

Integration tests verify that our infrastructure adapters (repositories, cache, carrier connectors) work correctly with their respective external services or mocks.

Test Coverage

Redis Cache Adapter (redis-cache.adapter.spec.ts)

• ✅ Get and set operations with various data types
• ✅ TTL (Time To Live) functionality
• ✅ Delete operations (single, multiple, clear all)
• ✅ Statistics tracking (hits, misses, hit rate)
• ✅ Error handling and resilience
• ✅ Complex data structures (nested objects, arrays)
• ✅ Key patterns and namespacing

Booking Repository (booking.repository.spec.ts)

• ✅ Save new bookings
• ✅ Update existing bookings
• ✅ Find by ID, booking number, organization, status
• ✅ Delete bookings
• ✅ Complex scenarios with nested data (shipper, consignee)
• ✅ Data integrity verification

Maersk Connector (maersk.connector.spec.ts)

• ✅ Search rates with successful responses
• ✅ Request/response mapping
• ✅ Surcharge handling
• ✅ Vessel and service information
• ✅ Empty results handling
• ✅ Error scenarios (timeout, API errors, malformed data)
• ✅ Circuit breaker behavior
• ✅ Health check functionality

Running Integration Tests

Prerequisites

For Redis tests:

• Redis server running on localhost:6379 (or set REDIS_HOST and REDIS_PORT)
• Tests use Redis DB 1 by default (not DB 0)

For Repository tests:

• PostgreSQL server running on localhost:5432 (or set TEST_DB_* variables)
• Tests will create a temporary database: xpeditis_test
• Tests use synchronize: true and dropSchema: true for clean slate

Commands

# Run all integration tests
npm run test:integration

# Run with coverage report
npm run test:integration:cov

# Run in watch mode (for development)
npm run test:integration:watch

# Run specific test file
npm run test:integration -- redis-cache.adapter.spec.ts

Environment Variables

Create a .env.test file or set these variables:

# Database (for repository tests)
TEST_DB_HOST=localhost
TEST_DB_PORT=5432
TEST_DB_USER=postgres
TEST_DB_PASSWORD=postgres
TEST_DB_NAME=xpeditis_test

# Redis (for cache tests)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=1

# Carrier APIs (for connector tests - mocked in tests)
MAERSK_API_BASE_URL=https://api.maersk.com
MAERSK_API_KEY=test-api-key

Test Strategy

Redis Cache Tests

• Uses ioredis-mock for isolated testing
• No real Redis connection required for CI/CD
• Fast execution, no external dependencies

Repository Tests

• Option 1 (Current): Real PostgreSQL database with synchronize: true
• Option 2 (Recommended for CI): Use testcontainers for ephemeral PostgreSQL
• Tests create and destroy schema between runs
• Each test cleans up its data in afterEach hooks

Carrier Connector Tests

• Uses mocked HTTP calls (jest mocks on axios)
• No real API calls to carriers
• Simulates various response scenarios
• Tests circuit breaker and retry logic

Coverage Goals

Target coverage for infrastructure layer:

• Redis Cache Adapter: 90%+
• Repositories: 80%+
• Carrier Connectors: 80%+

Best Practices

1. Isolation: Each test should be independent and not rely on other tests
2. Cleanup: Always clean up test data in afterEach or afterAll
3. Mocking: Use mocks for external services where appropriate
4. Assertions: Be specific with assertions - test both happy paths and error cases
5. Performance: Keep tests fast (< 5 seconds per test suite)

Troubleshooting

"Cannot connect to Redis"

• Ensure Redis is running: redis-cli ping should return PONG
• Check REDIS_HOST and REDIS_PORT environment variables
• For CI: ensure ioredis-mock is properly installed

"Database connection failed"

• Ensure PostgreSQL is running
• Verify credentials in environment variables
• Check that user has permission to create databases

"Tests timeout"

• Check testTimeout in jest-integration.json (default: 30s)
• Ensure database/Redis are responsive
• Look for hanging promises (missing await)

Future Improvements

• Add testcontainers for PostgreSQL (better CI/CD)
• Add integration tests for User and Organization repositories
• Add integration tests for additional carrier connectors (MSC, CMA CGM)
• Add performance benchmarks
• Add integration tests for S3 storage adapter
• Add integration tests for email service