# 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

```bash
# 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:

```bash
# 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