Integration Test Runner

Run and manage integration test suites with automatic environment setup, database seeding, service orchestration, and cleanup.

Features

• Automated setup - Database creation, migrations, seeding
• Service orchestration - Start/stop dependent services
• Environment management - Test-specific configurations
• Comprehensive reporting - Detailed results and logs
• Proper cleanup - No test pollution or leftover state
• Fast feedback - Fail fast on setup errors

Installation

/plugin install integration-test-runner@claude-code-plugins-plus

Usage

Run all integration tests

/run-integration

Run specific test suite

/run-integration api
/run-integration --suite user-workflows

Run with coverage

/run-integration --coverage

Use shortcut

/rit

What It Does

1. Pre-Test Setup

• Validates environment configuration
• Checks database connectivity
• Verifies service availability
• Confirms no port conflicts

2. Environment Preparation

• Creates/resets test database
• Runs database migrations
• Seeds test data
• Starts dependent services (Redis, queues, etc.)
• Initializes test containers

3. Test Execution

• Runs test suites in logical order
• Captures detailed execution logs
• Reports progress in real-time
• Handles failures gracefully
• Collects code coverage (if enabled)

4. Post-Test Cleanup

• Drops test database or truncates tables
• Stops test services and containers
• Removes temporary files
• Clears test caches
• Resets environment

5. Report Generation

• Pass/fail counts
• Execution times
• Failed test details with stack traces
• Code coverage metrics
• Service logs for debugging

Test Types Supported

• API Integration - REST/GraphQL endpoint testing
• Database Operations - CRUD operations, transactions
• Service Communication - Microservice interactions
• External APIs - Third-party integrations (mocked or sandboxed)
• Message Queues - Pub/sub, task queues
• File Operations - Upload/download workflows
• Authentication - Login, tokens, sessions

Example Workflow

# 1. Plugin runs pre-flight checks
Checking environment... 
Database available... 
Required services... 

# 2. Sets up test environment
Creating test database... 
Running migrations... 
Seeding test data... 
Starting Redis... 

# 3. Executes test suites
Running API tests... 12/12 passed
Running workflow tests... 8/8 passed
Running integration tests... 15/16 passed (1 failure)

# 4. Generates report
Results: 35/36 passed (97.2%)
…

Configuration

The plugin looks for test configuration in:

• test/integration/config.json
• .env.test
• docker-compose.test.yml
• Project-specific test configs

Example configuration:

{
  "database": {
    "name": "myapp_test",
    "reset": true,
    "seed": "test/fixtures/seed.sql"
  },
  "services": {
    "redis": "redis://localhost:6380",
    "queue": "amqp://localhost:5673"
  },
  "env": {
    "NODE_ENV": "test",
    "LOG_LEVEL": "error"
  }
}

Best Practices

The plugin enforces integration testing best practices:

• Test isolation - No shared state between tests
• Idempotency - Can run multiple times safely
• Realistic data - Test data resembles production
• Proper cleanup - Leaves no trace
• Clear reporting - Easy failure diagnosis
• Fast execution - Optimized for speed

Requirements

• Claude Code CLI
• Testing framework (Jest, pytest, RSpec, etc.)
• Database access (PostgreSQL, MySQL, MongoDB, etc.)
• Docker (optional, for service containers)

Tips

1. Keep tests fast - Use minimal data seeding
2. Parallelize when possible - Independent tests can run concurrently
3. Mock external APIs - Use sandboxes or mocks for third parties
4. Use transactions - Rollback after each test for speed
5. Tag tests - Separate slow tests for CI optimization

Troubleshooting

Tests fail with "connection refused"

Ensure dependent services are running. Check Docker containers or local services.

Database errors during setup

Verify migrations are current and database user has proper permissions.

Timeouts during test execution

Increase test timeout values or optimize slow queries.

Port conflicts

Change test service ports or stop conflicting processes.

License

MIT