149 lines
4.5 KiB
Markdown
149 lines
4.5 KiB
Markdown
# 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
|