Guide for running integration tests against external services (real APIs and LocalStack).
Overview#
External integration tests verify that our service integrations work correctly with real APIs. These tests are disabled by default and require explicit configuration to run.
Test Categories#
| Service | Test File | Tests | Environment Flag |
|---|---|---|---|
| ElevenLabs TTS | services/ai/src/__tests__/elevenlabs-integration.test.ts |
22 | ELEVENLABS_INTEGRATION_ENABLED |
| OpenRouter LLM | services/ai/src/__tests__/providers/openrouter-integration.test.ts |
19 | OPENROUTER_INTEGRATION_ENABLED |
| Stripe Payments | services/payment-orchestrator/src/__tests__/stripe/stripe-integration.test.ts |
19 | STRIPE_INTEGRATION_ENABLED |
| AWS (LocalStack) | services/media/src/__tests__/aws-localstack-integration.test.ts |
17 | AWS_LOCALSTACK_ENABLED |
ElevenLabs Integration Tests#
Tests for text-to-speech, voice management, and model APIs.
Required Environment Variables#
bash
ELEVENLABS_INTEGRATION_ENABLED=true
ELEVENLABS_API_KEY=<your-api-key>
# Optional (cost control)
ELEVENLABS_TEST_VOICE_ID=<voice-id> # Use specific voice
ELEVENLABS_RUN_TTS_TESTS=true # Enable TTS tests (costs characters)
Running Tests#
bash
# Run all ElevenLabs integration tests
npm run test:unit -- "services/ai/src/__tests__/elevenlabs-integration.test.ts"
# Run with TTS tests enabled
ELEVENLABS_INTEGRATION_ENABLED=true \
ELEVENLABS_API_KEY=your-key \
ELEVENLABS_RUN_TTS_TESTS=true \
npm run test:unit -- "services/ai/src/__tests__/elevenlabs-integration.test.ts"
Test Coverage#
- Voice API:
getVoices,getVoice,searchVoices,getVoiceSettings - Model API:
getModels, model capability detection - Usage API:
getUsage,getCharacterUsage - TTS:
textToSpeech,textToSpeechStream(optional)
OpenRouter Integration Tests#
Tests for LLM completions, embeddings, and model discovery.
Required Environment Variables#
bash
OPENROUTER_INTEGRATION_ENABLED=true
OPENROUTER_API_KEY=<your-api-key>
# Optional (cost control)
OPENROUTER_RUN_COMPLETION_TESTS=true # Enable completion tests
OPENROUTER_RUN_EMBEDDING_TESTS=true # Enable embedding tests
OPENROUTER_RUN_IMAGE_TESTS=true # Enable image generation tests
Running Tests#
bash
# Run all OpenRouter integration tests
npm run test:unit -- "services/ai/src/__tests__/providers/openrouter-integration.test.ts"
# Run with completion tests
OPENROUTER_INTEGRATION_ENABLED=true \
OPENROUTER_API_KEY=your-key \
OPENROUTER_RUN_COMPLETION_TESTS=true \
npm run test:unit -- "services/ai/src/__tests__/providers/openrouter-integration.test.ts"
Test Coverage#
- Model Discovery:
fetchModelCapabilities, model caching - Health Check: API availability verification
- Completions:
complete,completeStream(optional) - Embeddings:
createEmbedding(optional) - Image Generation:
generateImage(optional)
Stripe Integration Tests (Test Mode)#
Tests for payment processing using Stripe's test mode.
Required Environment Variables#
bash
STRIPE_INTEGRATION_ENABLED=true
STRIPE_TEST_SECRET_KEY=sk_test_... # Must be a test mode key
Running Tests#
bash
# Run all Stripe integration tests
npm run test:unit -- "services/payment-orchestrator/src/__tests__/stripe/stripe-integration.test.ts"
Test Coverage#
- Customer API: create, retrieve, update, delete
- Payment Intents: create, retrieve, cancel
- Setup Intents: create, retrieve, cancel
- Payment Methods: list payment methods
- Error Handling: invalid API keys, missing resources
Safety Notes#
- Only use test mode keys (
sk_test_...) - No real money is charged in test mode
- Test card numbers:
4242424242424242
AWS LocalStack Integration Tests#
Tests for AWS services using LocalStack for local development.
LocalStack Setup#
bash
# Start LocalStack
docker run -d -p 4566:4566 localstack/localstack
# Create test bucket
awslocal s3 mb s3://test-bucket
# Verify LocalStack is running
awslocal s3 ls
Required Environment Variables#
bash
AWS_LOCALSTACK_ENABLED=true
AWS_ENDPOINT=http://localhost:4566
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
AWS_REGION=us-east-1
AWS_TEST_BUCKET=test-bucket
Running Tests#
bash
# Run all LocalStack tests
npm run test:unit -- "services/media/src/__tests__/aws-localstack-integration.test.ts"
# Full example
AWS_LOCALSTACK_ENABLED=true \
AWS_ENDPOINT=http://localhost:4566 \
AWS_ACCESS_KEY_ID=test \
AWS_SECRET_ACCESS_KEY=test \
AWS_REGION=us-east-1 \
AWS_TEST_BUCKET=test-bucket \
npm run test:unit -- "services/media/src/__tests__/aws-localstack-integration.test.ts"
Test Coverage#
- S3 Upload:
uploadFile, storage classes, binary data - S3 Download:
downloadFile, error handling - S3 Metadata:
getFileMetadata - S3 Delete:
deleteFile, idempotency - S3 List:
listFileswith prefix filtering - Presigned URLs: GET and PUT URLs
- File Copy:
copyFile - Health Check: bucket accessibility
CI/CD Integration#
GitHub Actions Example#
yaml
jobs:
integration-tests:
runs-on: ubuntu-latest
services:
localstack:
image: localstack/localstack
ports:
- 4566:4566
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Setup LocalStack
run: |
pip install awscli-local
awslocal s3 mb s3://test-bucket
- name: Run AWS Integration Tests
env:
AWS_LOCALSTACK_ENABLED: 'true'
AWS_ENDPOINT: 'http://localhost:4566'
AWS_ACCESS_KEY_ID: 'test'
AWS_SECRET_ACCESS_KEY: 'test'
AWS_TEST_BUCKET: 'test-bucket'
run:
npm run test:unit --
"services/media/src/__tests__/aws-localstack-integration.test.ts"
Running All Integration Tests#
bash
# Script to run all integration tests (with proper credentials)
#!/bin/bash
# ElevenLabs
ELEVENLABS_INTEGRATION_ENABLED=true \
ELEVENLABS_API_KEY=$ELEVENLABS_API_KEY \
npm run test:unit -- "elevenlabs-integration" || exit 1
# OpenRouter
OPENROUTER_INTEGRATION_ENABLED=true \
OPENROUTER_API_KEY=$OPENROUTER_API_KEY \
npm run test:unit -- "openrouter-integration" || exit 1
# Stripe
STRIPE_INTEGRATION_ENABLED=true \
STRIPE_TEST_SECRET_KEY=$STRIPE_TEST_KEY \
npm run test:unit -- "stripe-integration" || exit 1
# AWS LocalStack (requires LocalStack running)
AWS_LOCALSTACK_ENABLED=true \
AWS_ENDPOINT=http://localhost:4566 \
npm run test:unit -- "aws-localstack-integration" || exit 1
echo "All integration tests passed!"
Best Practices#
- Never commit API keys - Use environment variables or secrets management
- Use test modes - Stripe test mode, LocalStack for AWS
- Control costs - Use optional flags to disable expensive operations
- Clean up resources - Tests should clean up created resources in
afterAll - Skip by default - Integration tests skip unless explicitly enabled
- Document requirements - Each test file includes setup instructions
Troubleshooting#
Tests Skipped#
If tests are being skipped, ensure:
- Environment flag is set (e.g.,
ELEVENLABS_INTEGRATION_ENABLED=true) - API key is provided and valid
- For LocalStack: container is running and bucket exists
Connection Errors#
- Check network connectivity
- Verify API endpoint URLs
- For LocalStack: ensure port 4566 is accessible
Authentication Errors#
- Verify API keys are valid and not expired
- Check key permissions match required operations
- For Stripe: ensure using test mode key (
sk_test_...)
Resource Cleanup#
If tests fail to clean up resources:
- ElevenLabs: Cloned voices may remain (check dashboard)
- Stripe: Test customers persist (use Stripe dashboard to clean)
- LocalStack: Restart container to reset state