# External Integration Tests

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: `listFiles` with 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

1. **Never commit API keys** - Use environment variables or secrets management
2. **Use test modes** - Stripe test mode, LocalStack for AWS
3. **Control costs** - Use optional flags to disable expensive operations
4. **Clean up resources** - Tests should clean up created resources in
   `afterAll`
5. **Skip by default** - Integration tests skip unless explicitly enabled
6. **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
