Add integration tests README documentation (FRE-4522)

Documentation for integration test suite including:
- Test file descriptions and coverage
- External provider mock configuration
- Running tests commands
- CI integration requirements
- Environment variables needed
- Test strategy and error scenarios

packages/integration-tests/README.md

@@ -0,0 +1,131 @@
+# Notification Service Integration Tests
+
+This directory contains integration tests for all notification services in the ShieldAI system.
+
+## Test Files
+
+### Individual Service Tests
+
+- `email.service.integration.test.ts` - Integration tests for EmailService (Resend)
+- `sms.service.integration.test.ts` - Integration tests for SMSService (Twilio)
+- `push.service.integration.test.ts` - Integration tests for PushService (FCM/APNs)
+
+### Orchestration Tests
+
+- `notification.service.integration.test.ts` - Integration tests for NotificationService
+  - Tests rate limiting across all channels
+  - Tests deduplication logic
+  - Tests user preferences
+  - Tests template-based notifications
+
+### End-to-End Tests
+
+- `notifications.integration.test.ts` - Basic E2E tests for notification flow
+- `notifications.benchmark.ts` - Performance benchmarks
+
+## External Provider Mocks
+
+All external provider API calls are mocked:
+
+- **Resend (Email)**: Mocked via `vi.mock('resend')`
+- **Twilio (SMS)**: Mocked via `vi.mock('twilio')`
+- **Firebase Admin (Push)**: Mocked via `vi.mock('firebase-admin')`
+
+## Test Coverage
+
+### Email Service
+- ✅ Email validation
+- ✅ Rate limiting per user
+- ✅ Template-based sending
+- ✅ Batch sending
+- ✅ Attachment handling
+- ✅ Metadata handling
+- ✅ Error handling (API errors, network timeouts, invalid emails)
+
+### SMS Service
+- ✅ Phone number validation
+- ✅ Rate limiting per user
+- ✅ Batch sending
+- ✅ Metadata handling
+- ✅ Error handling (API errors, network timeouts, invalid numbers)
+
+### Push Service
+- ✅ FCM notification sending
+- ✅ APNs configuration
+- ✅ Data payload handling
+- ✅ Badge/sound/category settings
+- ✅ Rate limiting per user
+- ✅ Batch sending
+- ✅ Error handling
+
+### Notification Service
+- ✅ Multi-channel routing
+- ✅ Deduplication logic
+- ✅ User preferences
+- ✅ Rate limiting
+- ✅ Template resolution
+- ✅ Error handling and retry logic
+
+## Running Tests
+
+```bash
+# Run all integration tests
+npm run test:e2e
+
+# Run specific test file
+npm test -- email.service.integration.test.ts
+
+# Run with coverage
+npm run test:coverage
+```
+
+## CI Integration
+
+Tests are configured to run in CI with the following setup:
+
+1. Environment variables must be set for all providers
+2. Redis must be available for rate limiting and deduplication
+3. Tests use mocked external APIs for reliability
+
+### Required Environment Variables
+
+```bash
+# Resend (Email)
+RESEND_API_KEY=your_api_key
+
+# Twilio (SMS)
+TWILIO_ACCOUNT_SID=your_account_sid
+TWILIO_AUTH_TOKEN=your_auth_token
+TWILIO_MESSAGING_SERVICE_SID=your_service_sid
+
+# Firebase (Push)
+FCM_PRIVATE_KEY=your_private_key
+FCM_PROJECT_ID=your_project_id
+FCM_CLIENT_EMAIL=your_client_email
+
+# Redis
+REDIS_URL=redis://localhost:6379
+DEDUP_WINDOW_SECONDS=300
+
+# Rate Limits
+EMAIL_RATE_LIMIT=60
+SMS_RATE_LIMIT=30
+PUSH_RATE_LIMIT=100
+RATE_LIMIT_WINDOW_SECONDS=60
+```
+
+## Test Strategy
+
+1. **Unit Tests**: Test individual service methods with mocked dependencies
+2. **Integration Tests**: Test service interactions and external API mocks
+3. **E2E Tests**: Test complete notification flows
+4. **Benchmark Tests**: Measure performance under load
+
+## Error Scenarios Tested
+
+- Network timeouts
+- API rate limits
+- Invalid input validation
+- Missing configuration
+- Provider authentication failures
+- Partial batch failures