integration-testing

---
description: MUST conduct integration testing WHEN components interact TO ensure system functionality.
globs: **/*test*.*,**/testing/**,**/*.spec.*,**/test/**,**/*testing*/**,**/integration/**,**/*integration*/**,**/*.test.*
---

# integration-testing

<version>1.1.0</version>

## Metadata
{
  "rule_id": "3615-integration-testing",
  "taxonomy": {
    "category": "Testing and Validation",
    "parent": "Testing and ValidationRule",
    "ancestors": [
      "Rule",
      "Testing and ValidationRule"
    ],
    "children": [
      "3616-unit-testing",
      "3617-system-testing"
    ]
  },
  "tags": [
    "integration",
    "testing",
    "validation",
    "quality assurance"
  ],
  "priority": "30",
  "inherits": [
    "000",
    "020",
    "030"
  ]
}

## Overview
{
  "purpose": "The purpose of this rule is to ensure that integration testing is conducted effectively to verify interactions between different system components.",
  "application": "This rule MUST be applied whenever components are combined or when new integrations are introduced. Developers MUST perform integration tests to validate that the components work together as intended.",
  "importance": "This rule is critical because integration testing helps identify issues that may not be apparent during unit testing, thereby ensuring the overall system functions correctly and meets quality standards."
}

## integration_test_strategy

{
  "description": "This section outlines the strategy for conducting integration tests to ensure that all components work together as expected.",
  "requirements": [
    "MUST define integration test cases that cover all interactions between components.",
    "MUST use a continuous integration pipeline to automatically run integration tests on code changes.",
    "SHOULD prioritize integration tests that involve critical business functionalities.",
    "NEVER skip integration tests when new components are added or existing components are modified."
  ]
}

## test_environment_setup

{
  "description": "This section describes the requirements for setting up the test environment necessary for integration testing.",
  "requirements": [
    "MUST replicate the production environment as closely as possible for integration tests.",
    "MUST ensure that all dependencies are correctly configured in the test environment.",
    "SHOULD use containerization tools, such as Docker, to create consistent testing environments.",
    "NEVER allow integration tests to run on a production environment to avoid impacting live systems."
  ]
}

## test_execution_and_reporting

{
  "description": "This section specifies the procedures for executing integration tests and reporting results.",
  "requirements": [
    "MUST execute integration tests regularly to catch integration issues early.",
    "MUST log and report test results in a clear and actionable format.",
    "SHOULD include both automated and manual integration tests in the reporting.",
    "NEVER ignore failed integration tests; all issues MUST be addressed before deployment."
  ]
}

<example>
Integration Testing Example for a User Management System

```python
import unittest
from unittest.mock import patch, MagicMock

# Sample UserService that interacts with a DatabaseService
class DatabaseService:
    def get_user(self, user_id):
        # Simulates fetching a user from the database
        pass

    def save_user(self, user):
        # Simulates saving a user to the database
        pass

class UserService:
    def __init__(self, database_service):
        self.database_service = database_service

    def get_user_details(self, user_id):
        user = self.database_service.get_user(user_id)
        if not user:
            raise ValueError('User not found')
        return user

    def create_user(self, user):
        if not user.get('name'):
            raise ValueError('User name is required')
        self.database_service.save_user(user)


# Integration tests for UserService and DatabaseService
class TestUserServiceIntegration(unittest.TestCase):
    @patch('__main__.DatabaseService')  # Mocking the DatabaseService
    def setUp(self, MockDatabaseService):
        self.mock_db_service = MockDatabaseService()
        self.user_service = UserService(self.mock_db_service)

    def test_get_user_details_success(self):
        # Arrange
        user_id = 1
        expected_user = {'id': 1, 'name': 'John Doe'}
        self.mock_db_service.get_user.return_value = expected_user

        # Act
        user = self.user_service.get_user_details(user_id)

        # Assert
        self.assertEqual(user, expected_user)
        self.mock_db_service.get_user.assert_called_once_with(user_id)

    def test_get_user_details_not_found(self):
        # Arrange
        user_id = 2
        self.mock_db_service.get_user.return_value = None

        # Act & Assert
        with self.assertRaises(ValueError) as context:
            self.user_service.get_user_details(user_id)
        self.assertEqual(str(context.exception), 'User not found')

    def test_create_user_success(self):
        # Arrange
        user = {'name': 'Jane Doe'}

        # Act
        self.user_service.create_user(user)

        # Assert
        self.mock_db_service.save_user.assert_called_once_with(user)

    def test_create_user_missing_name(self):
        # Arrange
        user = {}  # Missing name

        # Act & Assert
        with self.assertRaises(ValueError) as context:
            self.user_service.create_user(user)
        self.assertEqual(str(context.exception), 'User name is required')


if __name__ == '__main__':
    unittest.main()
```

This example demonstrates integration testing principles by testing interactions between the UserService and the mocked DatabaseService. The code is organized into distinct classes, with clear responsibilities for each service.

1. **Clear Code Organization**: The UserService handles user-related business logic, while the DatabaseService simulates database operations. Each class has a single responsibility, making it easier to maintain and test.

2. **Integration Tests**: The TestUserServiceIntegration class uses unittest to define integration tests that validate how UserService interacts with DatabaseService. It covers both successful and failure scenarios, ensuring that the integration points work as expected.

3. **Error Handling**: The UserService raises meaningful exceptions if the user is not found or if required fields are missing. The tests validate that these exceptions are raised appropriately.

4. **Proper Mocking**: The DatabaseService is mocked to isolate the UserService's functionality. This approach allows us to test the UserService independently of the actual database implementation, focusing solely on its integration with the database interface.

5. **Comprehensive Test Cases**: Each test case in the integration test class covers different interactions, ensuring that all aspects of the UserService's functionality are verified.

6. **Best Practices**: The example follows best practices by maintaining clarity, using meaningful assertions, and ensuring that tests can be run automatically as part of a continuous integration pipeline. This example is a realistic implementation that would be applicable in a production-like environment, making it educational and practical.
</example>

<danger>
{
  "critical_violations": [
    "NEVER skip integration testing when adding new external libraries that interact with existing components.",
    "NEVER ignore integration test failures during the development cycle; all issues MUST be resolved before merging code.",
    "NEVER conduct integration tests without properly configuring the test environment to match production settings.",
    "NEVER run integration tests without including all relevant system components; partial testing can lead to undetected failures.",
    "NEVER assume that unit tests are sufficient to guarantee integration success; integration tests MUST be performed for all critical interactions."
  ],
  "specific_risks": [
    "Ignoring integration tests can lead to undetected bugs that affect system stability, risking application crashes in production.",
    "Failing to resolve integration test failures can result in deploying broken features, leading to loss of user trust and potential revenue loss.",
    "Improper test environment configurations can cause false positives or negatives in tests, leading developers to mistakenly believe the system is functioning correctly.",
    "Running incomplete integration tests can allow critical integration points to fail unnoticed, resulting in system failures and degraded user experience.",
    "Relying solely on unit tests can create a false sense of security, as unit tests do not account for interactions between components, potentially leading to significant integration issues."
  ]
}
</danger>