Eve library

External Integration Tests

Guide

Revision 1

On this page

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