/run-integration

Integration Test Runner

Run integration tests with comprehensive environment setup, database seeding, service orchestration, and cleanup.

Purpose

Execute integration tests that verify interactions between multiple system components:

• API endpoints with database operations
• Microservices communication
• Third-party service integrations
• Full request/response workflows
• Database transactions and state changes

Pre-Test Setup

Before running integration tests, ensure:

1. Environment Configuration

   • Check for test environment variables
   • Verify test database connections
   • Confirm test API keys/credentials
   • Validate service dependencies are available

2. Database Preparation

   • Create/reset test database
   • Run migrations
   • Seed test data
   • Clear any existing test data

3. Service Dependencies

   • Start required services (Redis, message queues, etc.)
   • Check service health endpoints
   • Initialize mock services if needed
   • Set up test containers (Docker/Testcontainers)

4. State Management

   • Clear caches
   • Reset file system test directories
   • Initialize test state

Test Execution

Run integration tests with:

# Run all integration tests
/run-integration

# Run specific test suite
/run-integration api

# Run with specific environment
/run-integration --env staging

# Run with coverage
/run-integration --coverage

Execution Process

1. Pre-flight checks

   • Validate environment configuration
   • Check database connectivity
   • Verify service availability
   • Confirm no conflicting processes

2. Setup phase

   • Initialize test database
   • Seed required data
   • Start dependent services
   • Configure test environment

3. Run tests

   • Execute test suites in order
   • Capture detailed logs
   • Report progress
   • Handle test failures gracefully

4. Teardown phase

   • Clean up test data
   • Stop test services
   • Reset environment
   • Generate test reports

Test Organization

Structure integration tests by:

• API routes - Endpoint-specific tests
• User workflows - End-to-end user journeys
• Service interactions - Cross-service communication
• Data flows - Multi-step data processing

Reporting

Generate comprehensive reports with:

• Test results (pass/fail counts)
• Execution time per test
• Failed test details with stack traces
• Code coverage (if enabled)
• Service logs for failures
• Database state at failure points

Cleanup

After tests complete:

• Drop test database or truncate tables
• Stop test containers/services
• Remove temporary files
• Clear test caches
• Reset environment variables

Best Practices Applied

• Isolation - Tests don't depend on each other
• Idempotency - Tests can run multiple times safely
• Fast feedback - Fail fast on setup errors
• Clear reporting - Easy to identify failures
• Proper cleanup - No test pollution
• Realistic data - Test data resembles production

Example Output

Integration Test Runner
=======================

Setup Phase:
 Database connection verified
 Test database created and migrated
 Test data seeded (50 users, 200 products)
 Redis cache cleared
 Services healthy: api, worker, notifications

Running Tests:
 API Authentication Tests (5/5 passed) - 2.3s
 User Management Tests (12/12 passed) - 5.1s
 Order Processing Tests (8/8 passed) - 8.7s
 Payment Integration Tests (3/4 passed) - 4.2s
  └─ test_refund_webhook_handling FAILED
 Notification Tests (6/6 passed) - 3.1s

Results: 34/35 tests passed (97.1%)
Total time: 23.4s
Coverage: 78.3%

Teardown Phase:
 Test database dropped
 Services stopped
 Temp files removed

Report saved to: test-results/integration-2025-10-11-14-30.json

Troubleshooting

Common issues:

• Connection refused - Check service is running
• Database errors - Verify migrations are current
• Timeout errors - Increase test timeouts
• Port conflicts - Ensure test ports are available
• Permission errors - Check file/database permissions