Integration Test Patterns

Your unit tests mock the database and pass with flying colors. Then you deploy and discover that a Drizzle ORM migration changed a column type from varchar(255) to text, which caused your unique constraint to silently stop working. The mock never knew. Integration tests exist to catch the things that happen when real components talk to each other — the exact place where bugs hide.

What You’ll Walk Away With

• Patterns for database integration tests with proper setup, teardown, and isolation
• API contract testing workflows that catch breaking changes across services
• Strategies for testing message queues, caches, and external service integrations
• AI prompts that generate complete test infrastructure, not just test cases
• Techniques for keeping integration tests fast enough to run in CI

Database Integration Testing

The Test Database Strategy

Integration tests need a real database, but not your production one. Set up an isolated test database that resets between tests.

Cursor

@src/lib/db/schema.ts @tests/setup.ts
Create a database integration test setup for our Drizzle ORM + PostgreSQL project:

1. A setup file that:
   - Creates a test database (or uses a container via testcontainers)
   - Runs all migrations before the test suite
   - Provides a clean transaction wrapper per test (rollback after each)
   - Exports a `getTestDb()` helper that returns an isolated database connection

2. An example test for UserRepository.create that:
   - Uses the real database (not mocks)
   - Verifies the record exists after creation
   - Checks unique constraint enforcement (duplicate email)
   - Verifies cascade deletes work correctly
   - Tests NULL handling for optional fields

Follow our existing test patterns in @tests/setup.ts

Claude Code

claude "Create a complete database integration test infrastructure:

1. Install and configure testcontainers for PostgreSQL:
   - Auto-start a PostgreSQL container before tests
   - Run migrations automatically
   - Provide per-test transaction isolation

2. Create /tests/integration/db-setup.ts with:
   - beforeAll: start container, run migrations
   - beforeEach: begin transaction
   - afterEach: rollback transaction
   - afterAll: stop container

3. Create /tests/integration/user-repository.integration.test.ts with tests:
   - Insert and retrieve a user (verify all fields round-trip correctly)
   - Unique email constraint (expect proper error, not crash)
   - Pagination (insert 50 users, verify page 2 returns correct 10)
   - Full-text search (if supported by our schema)
   - Concurrent inserts (same email, only one should succeed)

Run the tests after creating them. Fix any issues."

Codex

Set up database integration testing for this project:
1. Configure testcontainers for PostgreSQL
2. Create test infrastructure with per-test isolation
3. Generate integration tests for all repository classes
4. Verify tests pass with a real database
5. Add to CI pipeline configuration

Focus on testing database behaviors that unit tests with mocks cannot catch:
- Constraint enforcement (unique, foreign key, check)
- Transaction isolation and rollback
- Query performance with realistic data volumes
- Migration compatibility

Tip

Copy-paste prompt for database integration tests:

Generate integration tests for OrderRepository that use a REAL PostgreSQL database.

Test these database-specific behaviors:
1. Foreign key enforcement: Creating an order with a non-existent user_id should fail
2. Transaction rollback: If order items insert fails, the order header should also roll back
3. Optimistic locking: Two concurrent updates to the same order - one should fail with a version conflict
4. JSON column handling: Storing and retrieving order metadata as JSONB
5. Date range queries: Orders between two timestamps with timezone awareness
6. Soft delete: Deleted orders should not appear in findAll but should appear in findIncludingDeleted
7. Bulk insert performance: Inserting 1000 orders should complete in under 2 seconds

Use testcontainers for the database. Isolate each test with a transaction rollback.
Include realistic test data using our OrderFactory.

API Contract Testing

Consumer-Driven Contract Tests

When your service consumes another service’s API, contract tests verify the integration without running both services.

Tip

Copy-paste prompt for API contract tests:

Generate consumer-driven contract tests for our order-service's integration with the payment-service API.

Our order-service calls these payment-service endpoints:
1. POST /payments - Create a payment (amount, currency, method, orderId)
2. GET /payments/{id} - Get payment status
3. POST /payments/{id}/refund - Refund a payment (amount, reason)

For each endpoint, generate:
- A Pact consumer test that defines what our service expects
- The expected request format (headers, body, query params)
- The expected response format for success AND error cases
- Provider state descriptions ("a payment with id X exists", "payment X is refundable")

Use Pact.js for the contract framework. Save to /tests/contracts/payment-service.pact.test.ts.
The generated pact file should be publishable to our Pact broker.

Message Queue Testing

Testing event-driven integrations requires verifying message publication, consumption, and ordering.

Tip

Copy-paste prompt for message queue integration tests:

Generate integration tests for our RabbitMQ event system.

Test the OrderCreated event flow:
1. When order-service publishes OrderCreated:
   - The message conforms to the event schema (validate against /schemas/order-created.json)
   - The message is published to the correct exchange with correct routing key
   - The message includes correlation ID for tracing

2. When inventory-service consumes OrderCreated:
   - Stock is reserved for each line item
   - If stock is insufficient, a StockReservationFailed event is published
   - If reservation succeeds, a StockReserved event is published
   - Messages are acknowledged only after successful processing
   - Failed messages go to the dead-letter queue after 3 retries

3. Event ordering:
   - Multiple OrderCreated events for the same product are processed sequentially
   - Events for different products can be processed in parallel

Use testcontainers for RabbitMQ. Include a helper to wait for async event processing.

External Service Testing

The Stub Server Pattern

For external APIs you do not control (Stripe, Twilio, SendGrid), use stub servers that simulate the API behavior.

Cursor

Create a stub server for the Stripe API that we can use in integration tests.

The stub should handle:
1. POST /v1/charges - Return success with a charge ID
2. POST /v1/charges - Return 402 when amount > 999999 (simulates declined)
3. POST /v1/refunds - Return success with refund ID
4. GET /v1/charges/{id} - Return charge details for known IDs, 404 for unknown

Implementation:
- Use Express with a random port (for parallel test execution)
- Store created charges in memory (so GET returns what POST created)
- Include a reset() method to clear state between tests
- Export a factory: createStripeStub() returns { url, server, reset }

Save to /tests/stubs/stripe.stub.ts

Claude Code

claude "Create a comprehensive Stripe API stub for integration testing.

Save to /tests/stubs/stripe.stub.ts with:
- Express server on random port
- In-memory charge and refund storage
- Configurable error responses for testing failure paths
- Request logging for test assertions
- Automatic cleanup in afterAll hooks

Then create /tests/integration/payment.integration.test.ts that:
- Uses the Stripe stub instead of the real API
- Tests: successful payment, declined card, refund, partial refund
- Verifies our service handles each Stripe response correctly
- Verifies retry logic for transient failures (500 responses)

Run tests after creation."

Codex

Create stub servers for all external API integrations in this project.
Check /src/clients/ for the external services we call.
For each external service:
1. Create a stub server in /tests/stubs/
2. Support success and failure responses
3. Create integration tests that use the stubs
4. Verify our error handling for each failure mode

Include a test helper that starts all stubs and injects their URLs
into our service configuration.

Keeping Integration Tests Fast

1. Parallelize with isolation

   Run independent test suites in parallel. Each suite gets its own database schema or container.

2. Shared test containers

   Start the database container once for the entire suite, not per test file. Use transaction rollback for per-test isolation.

3. Selective running

   Tag tests and run only affected integration tests: npm test -- --testPathPattern=integration/order when working on order code.

4. Database seeding vs. per-test setup

   For read-only tests, seed reference data once. Only create per-test data for tests that modify it.

5. Container caching in CI

   Cache Docker images in your CI pipeline to avoid pulling them on every run.

Tip

Copy-paste prompt for optimizing slow integration tests:

Our integration test suite takes 12 minutes. Analyze /tests/integration/ and optimize:

1. Identify tests that start their own database when they could share one
2. Find tests that seed large datasets when only 2-3 rows are needed
3. Detect tests that wait for fixed timeouts instead of polling for conditions
4. Spot tests that clean up with DELETE instead of transaction rollback
5. Flag tests that call external services instead of using stubs
6. Identify test files that could run in parallel (no shared mutable state)

For each optimization: estimated time savings and the specific change needed.
Target: get the suite under 4 minutes.

When This Breaks

“Integration tests are flaky and fail randomly in CI.” The top causes: shared database state between tests, hardcoded ports conflicting in parallel runs, and timing-dependent assertions. Use transaction rollback for isolation, random ports for services, and polling loops instead of setTimeout for async operations.

“Tests pass locally but fail in CI.” Check for differences in database versions, missing environment variables, and Docker networking. Use testcontainers to ensure the same database version runs everywhere. Pin your container images to specific versions.

“Integration tests are too slow to run on every commit.” Run only affected integration tests on commits (based on changed files). Run the full suite on PR merge and nightly. This gives fast feedback during development and comprehensive verification before merge.

“The AI generated tests that depend on insertion order.” Database query results are unordered unless you specify ORDER BY. Ask the AI to “sort results before asserting, or assert on set membership rather than array equality.”

What’s Next

E2E Testing Test complete user journeys from UI to database.

API Testing API contract testing and endpoint verification.

Test Data Management Factories and fixtures for consistent test data.