> For the complete documentation index, see [llms.txt](https://docs.qyrus.com/test-orchestration/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qyrus.com/test-orchestration/use-cases-and-examples/integration-testing.md).

# Integration Testing

## Overview

Integration Testing validates how different system components, services, and external systems work together. It focuses on the interfaces and data flows between components rather than individual component functionality.

{% hint style="info" %}
🔗 **Component Integration**

Integration Testing verifies:

* Services communicate correctly
* Data flows properly between systems
* External integrations work
* APIs return expected data
* Systems handle each other's failures
  {% endhint %}

***

## When to Use Integration Testing

### ✅ Good Use Cases

| Scenario                 | Why Integration                      |
| ------------------------ | ------------------------------------ |
| **Microservices**        | Multiple services must work together |
| **API Interactions**     | Service to service communication     |
| **Database Integration** | Data persistence and retrieval       |
| **Third-Party APIs**     | Vendor integrations                  |
| **Message Queues**       | Async communication between services |
| **File Systems**         | File operations and access           |

### ❌ Anti-Patterns (Don't Do)

* ❌ Test individual component logic (use unit tests)
* ❌ Integration without mocking external services
* ❌ Test UI in integration tests (use E2E)
* ❌ Skip unit tests in favor of integration (pyramid strategy)
* ❌ Leave external dependencies uncontrolled

***

## Types of Integration

### API to API Integration

Service A calls Service B:

```
Service A:
  [Make request to Service B]
  ↓
Service B:
  [Process request]
  [Return response]
  ↓
Service A:
  [Handle response]
  [Use data]
  [Verify result]
```

### Service to Database

Service reading/writing data:

```
Service:
  [Prepare query/data]
  [Execute against database]
  ↓
Database:
  [Process operation]
  [Return result/confirmation]
  ↓
Service:
  [Process result]
  [Verify persistence]
```

### Asynchronous Integration

Message-based communication:

```
Service A:
  [Publish event/message]
  ↓
Message Queue:
  [Store message]
  ↓
Service B:
  [Consume message]
  [Process]
  [Publish response]
```

### External Service Integration

Third-party service:

```
System:
  [Prepare request]
  [Call external API]
  ↓
External Service:
  [Process]
  [Return response]
  ↓
System:
  [Handle response]
  [Handle errors]
  [Continue workflow]
```

***

## Practical Examples

### Example 1: User Creation Across Services

```
Workflow: Create user (multiple services involved)

Services:
- User Service (manages user records)
- Email Service (sends emails)
- Profile Service (manages profiles)
- Notification Service (sends notifications)

Steps:

1. [API: POST /users (User Service)]
   Input:
     {
       "email": "user@example.com",
       "name": "Test User",
       "role": "customer"
     }
   
   Process:
   - Validate input
   - Check email unique
   - Hash password
   - Create in database
   
   Output:
     {
       "user_id": "usr_123",
       "email": "user@example.com",
       "created_at": "2024-01-15T14:30:00Z"
     }

2. [API: POST /profiles (Profile Service)]
   Input:
     {
       "user_id": "usr_123",
       "first_name": "Test",
       "last_name": "User"
     }
   
   Verify:
   - Profile created
   - Linked to user

3. [API: POST /emails/welcome (Email Service)]
   Input:
     {
       "to": "user@example.com",
       "template": "welcome",
       "user_id": "usr_123"
     }
   
   Verify:
   - Email sent
   - Correct template used
   - Correct recipient

4. [API: POST /notifications (Notification Service)]
   Input:
     {
       "user_id": "usr_123",
       "type": "user_created",
       "message": "Welcome to platform"
     }
   
   Verify:
   - Notification created
   - User can retrieve

5. [Verify Complete Integration]
   Check:
   - User exists in User Service
   - Profile exists in Profile Service
   - Email was sent
   - Notification created
   - All data consistent

Result: ✅ Complete user creation across all services
```

### Example 2: Order Processing Workflow

```
Workflow: Process order (multi-service integration)

Services:
- Order Service
- Payment Service
- Inventory Service
- Shipping Service
- Notification Service

Steps:

1. [Create Order]
   [Order Service: Create order]
     Input: {items, customer_id, total}
     Output: {order_id}
   
   Verify: Order created with status "pending"

2. [Process Payment]
   [Payment Service: Process payment]
     Input: {order_id, amount, payment_method}
     Output: {transaction_id, status}
   
   Verify: Payment successful, transaction recorded

3. [Reserve Inventory]
   [Inventory Service: Reserve items]
     Input: {order_id, items}
     Output: {reservation_id}
   
   Verify: Inventory reserved, quantity updated

4. [Create Shipment]
   [Shipping Service: Create shipment]
     Input: {order_id, items, address}
     Output: {shipment_id, tracking_number}
   
   Verify: Shipment created, tracking available

5. [Send Notifications]
   [Notification Service: Send confirmations]
     Input: {order_id, customer_id, type: "order_confirmed"}
     Output: {notification_id}
   
   Verify: Customer notified via email and SMS

6. [Verify Complete Integration]
   Check:
   - Order status updated
   - Payment recorded
   - Inventory reserved
   - Shipment tracking available
   - Customer notifications sent
   - All systems in sync

Result: ✅ Complete order processing across all services
```

### Example 3: Database Integration

```
Workflow: Data persistence and retrieval

Database: PostgreSQL
Service: User Management Service

Steps:

1. [Insert: Create user]
   SQL: INSERT INTO users (email, name, created_at)
   Values: ('user@test.com', 'Test', now())
   
   Result: user_id = 123

2. [Select: Retrieve user]
   SQL: SELECT * FROM users WHERE id = 123
   
   Verify:
   - User retrieved
   - All fields correct
   - Timestamp accurate

3. [Update: Modify user]
   SQL: UPDATE users SET name = 'Updated' WHERE id = 123
   
   Verify:
   - Update successful
   - Reflection in next query

4. [Select: Verify update]
   SQL: SELECT * FROM users WHERE id = 123
   
   Verify:
   - New name returned
   - Other fields unchanged

5. [Transaction: Multi-operation]
   BEGIN TRANSACTION
     INSERT INTO users (...) → user_id = 124
     INSERT INTO profiles (...) → profile_id = 456
   COMMIT
   
   Verify:
   - Both inserts succeeded
   - Linked correctly
   - No partial states

6. [Delete: Remove user]
   SQL: DELETE FROM users WHERE id = 123
   
   Verify:
   - User deleted
   - Cascading deletes if applicable

Result: ✅ Database integration working correctly
```

### Example 4: Third-Party Service Integration

```
Workflow: Stripe payment integration

External Service: Stripe API

Steps:

1. [Create payment intent]
   [Call: POST /v1/payment_intents]
   Input:
     {
       "amount": 9999,
       "currency": "usd",
       "payment_method": "card_123"
     }
   
   Output:
     {
       "client_secret": "secret_123",
       "status": "requires_payment_method"
     }

2. [Confirm payment]
   [Call: POST /v1/payment_intents/intent_id/confirm]
   Input:
     {
       "payment_method": "card_123"
     }
   
   Output:
     {
       "status": "succeeded",
       "charges": {...}
     }

3. [Verify charge]
   [Call: GET /v1/charges/charge_id]
   
   Verify:
   - Amount correct
   - Status: succeeded
   - Customer linked

4. [Verify webhook]
   [Listen for: payment_intent.succeeded]
   
   Verify:
   - Webhook received
   - Correct payload
   - Payment ID matches

5. [Verify in our system]
   [Check database]
   
   Verify:
   - Payment record created
   - Order updated
   - Amount recorded
   - Status saved

Result: ✅ Third-party integration working correctly
```

### Example 5: Async Message Queue Integration

```
Workflow: Async event processing

Services:
- Order Service (publishes events)
- Email Service (consumes events)
- Analytics Service (consumes events)

Steps:

1. [Order Created Event]
   [Order Service: Publish to queue]
   
   Event:
     {
       "type": "order.created",
       "order_id": "ord_123",
       "timestamp": "2024-01-15T14:30:00Z"
     }

2. [Email Service: Consume event]
   [Queue: Deliver to Email Service]
   
   Email Service:
   - Receives event
   - Sends order confirmation email
   - Publishes: "email.sent"

3. [Analytics Service: Consume event]
   [Queue: Deliver to Analytics Service]
   
   Analytics Service:
   - Receives event
   - Records order metrics
   - Publishes: "analytics.recorded"

4. [Verify async processing]
   Check:
   - Event in queue
   - Email sent (via logs)
   - Analytics recorded (via query)
   - No errors in processing
   - Order status updated

5. [Verify handling failures]
   [Test: Email service down]
   
   Verify:
   - Event remains in queue
   - Retry logic triggers
   - Email sent after service recovery
   - No data loss

Result: ✅ Async integration working correctly
```

***

## Mocking vs Real Services

### Full Integration (Real Services)

```
Pros:
✓ Tests real behavior
✓ Catches integration issues
✓ True end-to-end

Cons:
✗ Slower execution
✗ External dependency failures
✗ Test flakiness
✗ Harder to control edge cases

Use when: Critical paths, confidence important
```

### Partial Mocking (Mix)

```
Real services: 
- Your services (under test)

Mocked services:
- External APIs (Stripe, SendGrid)
- Slow operations
- Unpredictable services

Balance:
- Fast execution
- Realistic scenarios
- Controlled edge cases

Use when: Most testing (recommended)
```

### Full Mocking (All Mocked)

```
Mocked:
- All external services
- Database (in-memory)
- All integrations

Pros:
✓ Very fast
✓ Fully controlled
✓ No external dependencies

Cons:
✗ Not testing real integration
✗ Mock issues not caught
✗ Less confidence

Use when: Unit-level testing only
```

***

## Best Practices

### ✅ Do

* **Test real service interactions** - Mocking hides real issues
* **Use test credentials** - Don't use production
* **Verify both request and response** - Full validation
* **Test error paths** - Services fail
* **Use contracts** - Know expected formats
* **Clean up test data** - Don't pollute systems
* **Mock external services** - You don't control them
* **Test timeouts** - Services are slow sometimes

### ❌ Don't

* **Mock your own services** - Test real interaction
* **Ignore service failures** - Plan for outages
* **Test UI in integration** - Use E2E for that
* **Use production data** - Test data only
* **Hardcode test values** - Use variables
* **Leave test data behind** - Clean up after
* **Skip error scenarios** - That's when issues occur
* **Test without strategy** - Know what you're validating

***

## Test Data Management

### Isolated Test Data

```
Create:
[Test user] → unique email per test run
[Test order] → in test database
[Test payment] → mocked provider

Use:
[Execute integration]
[Verify interactions]

Clean up:
[Delete test user]
[Rollback test order]
[Clear mocked calls]
```

### Shared Test Data

```
Setup once:
[Create reference data]
[Product catalogs]
[User accounts]

Reuse:
[Run multiple tests]
[Same data]
[No cleanup between tests]

Careful:
[State changes affect others]
[Need careful sequencing]
[Tests may depend on order]
```

***

## Troubleshooting

### Issue: Service calls timeout

**Symptoms**:

* Tests fail with timeout
* Service slow to respond

**Causes**:

* Service actually slow
* Network issues
* Service down

**Solutions**:

1. Increase timeout
2. Check service health
3. Mock if external
4. Add retry logic

### Issue: Flaky integration tests

**Symptoms**:

* Pass sometimes, fail sometimes
* Inconsistent results

**Causes**:

* Race conditions
* Timing issues
* Service instability
* Data state issues

**Solutions**:

1. Add explicit waits
2. Use polling
3. Fix race conditions
4. Mock flaky services

### Issue: Data pollution

**Symptoms**:

* Tests interfere with each other
* State from previous tests affects current

**Causes**:

* Incomplete cleanup
* Shared test data
* Persistent state

**Solutions**:

1. Clean up after each test
2. Use isolated test data
3. Reset state between runs

***

## Related Topics

* [**API Workflow Testing**](/test-orchestration/use-cases-and-examples/api-workflow-testing.md) - Complex API scenarios
* [**Regression Testing**](/test-orchestration/use-cases-and-examples/regression-testing.md) - Integration in test suite
* [**Error Handling**](/test-orchestration/advanced-topics/error-handling.md) - Error scenarios
* [**Best Practices**](/test-orchestration/advanced-topics/best-practices.md) - Professional standards

***

## Summary

* **Integration Testing** validates component interactions
* **Test service communication** - APIs, databases, queues
* **Mix real and mocked** - Real your services, mock external
* **Verify both directions** - Request and response
* **Test error scenarios** - Services fail
* **Clean up data** - Don't pollute systems

***

**Next**: Learn about [Regression Testing](/test-orchestration/use-cases-and-examples/regression-testing.md) for automated test suites.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qyrus.com/test-orchestration/use-cases-and-examples/integration-testing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.